{"openapi":"3.0.0","info":{"title":"Auto-Translate Planner Application API","description":"API methods of this application cannot be called directly. Instead, you should trigger Crowdin's platform API endpoint, Crowdin will authorize your request and route it to this app.\n\nExample call for crowdin.com \n\n    curl --request GET \n    --url \"https://crowdin.com/api/v2/applications/auto-translate-planner/api/data?report=raw&projects=479\" \n    --header \"Authorization: Bearer 70cf05deasdas78c84c73c4cf986ee0a3ee911w1dsad384e3c4asd1qdbbcf6b6db5732e\" \nExample call for Crowdin Enterprise \n\n    curl --request GET \n    --url \"https://acme.crowdin.com/api/v2/applications/auto-translate-planner/api/data?report=raw&projects=479&startDate=2023-06-01T06%3A32%3A01.048Z&endDate=2023-06-23T06%3A32%3A01.048Z\" \n    --header \"Authorization: Bearer 70cf05dee35sad12rfes0a3ee911462e7b0723rfdfrg1e45bbcf6b6db5732e\" \n","version":"1.0.0","x-logo":{"url":"https://support.crowdin.com/assets/crowdin-logo.svg"}},"servers":[{"url":"{protocol}//{host}/api/v2/applications/auto-translate-planner/api","variables":{"protocol":{"default":"https","enum":["https","http"],"description":"Protocol (https for production)"},"host":{"default":"crowdin.com","description":"Crowdin host (crowdin.com or {organization}.crowdin.com for Enterprise)"}}}],"paths":{"/settings":{"get":{"summary":"Get Settings","description":"Whether the app auto-translates the project's new strings, and the file events that start its rules","operationId":"settings.get","tags":["Settings"],"parameters":[{"$ref":"#/components/parameters/PlannerProjectId"}],"responses":{"200":{"description":"The settings","content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/PlannerSettings"}}}}}},"default":{"$ref":"#/components/responses/PlannerFailure"}}},"put":{"summary":"Update Settings","description":"Turns the app on or off for the project and picks the events that start its rules. On, every enabled rule is checked against the project and the app adds the project's webhook; off always works, and the rules are kept. Changes the project, confirm with the user first","operationId":"settings.update","tags":["Settings"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId","enabled"],"properties":{"projectId":{"type":"integer"},"enabled":{"type":"boolean"},"events":{"type":"array","description":"Kept as they are when left out","items":{"type":"string","enum":["file.added","file.updated","file.reverted"]}},"version":{"$ref":"#/components/schemas/PlannerVersion"}}}}}},"responses":{"200":{"description":"The settings saved","content":{"application/json":{"schema":{"properties":{"data":{"$ref":"#/components/schemas/PlannerSettings"}}}}}},"default":{"$ref":"#/components/responses/PlannerFailure"}}}},"/rules":{"get":{"summary":"Get Rules","description":"The project's rules in priority order: for every target language of a file, the first enabled rule that matches the file and has the language translates it; the rules below take only the languages left","operationId":"rules.get","tags":["Rules"],"parameters":[{"$ref":"#/components/parameters/PlannerProjectId"}],"responses":{"200":{"description":"The rules","content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/PlannerRule"}},"version":{"$ref":"#/components/schemas/PlannerVersion"}}}}}}}},"default":{"$ref":"#/components/responses/PlannerFailure"}}},"put":{"summary":"Update Rules","description":"Replaces the project's whole list of rules; the order is the priority. While the app is on, every enabled rule must be complete and use what Get Rule Options lists; a rule that is off may stay a draft. Changes the project, confirm with the user first","operationId":"rules.update","tags":["Rules"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId","rules"],"properties":{"projectId":{"type":"integer"},"rules":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/PlannerRule"}},"version":{"$ref":"#/components/schemas/PlannerVersion"}}}}}},"responses":{"200":{"description":"The rules saved","content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/PlannerRule"}},"version":{"$ref":"#/components/schemas/PlannerVersion"}}}}}}}},"default":{"$ref":"#/components/responses/PlannerFailure"}}}},"/rule-options":{"get":{"summary":"Get Rule Options","description":"What the project's rules may use, and the languages Crowdin already auto-translates on its own","operationId":"rules.options","tags":["Rules"],"parameters":[{"$ref":"#/components/parameters/PlannerProjectId"}],"responses":{"200":{"description":"The options","content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"enterprise":{"type":"boolean"},"stringBased":{"type":"boolean"},"sourceLanguageId":{"type":"string"},"languages":{"type":"array","description":"The project's target languages","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"prompts":{"type":"array","description":"AI prompts with the pre-translate action the project may use","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"}}}},"engines":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"targets":{"type":"array","nullable":true,"description":"The languages the engine translates the project's source into; null for any","items":{"type":"string"}}}}},"limits":{"type":"object","properties":{"nameLength":{"type":"integer"},"instructionLength":{"type":"integer"},"minMatchRatio":{"type":"integer"},"maxMatchRatio":{"type":"integer"}}},"native":{"type":"object","nullable":true,"description":"crowdin.com only: the project's own auto-translation of new content (Project Settings), which Crowdin runs on every new file without the app. A rule with one of these languages would translate the same strings a second time, and AI or MT would be charged twice. Null when it is off","properties":{"methods":{"type":"array","description":"The ways it translates","items":{"type":"string","enum":["ai","mt","tm"]}},"languageIds":{"type":"array","description":"The languages it translates into","items":{"type":"string"}}}},"workflow":{"type":"array","description":"Crowdin Enterprise only: the steps of the project's workflow that translate new strings on their own (TM, MT or AI pre-translation). A rule with one of their languages would translate the same strings a second time. Empty on crowdin.com and without such steps","items":{"type":"object","properties":{"title":{"type":"string","description":"The step's name in the workflow"},"method":{"type":"string","enum":["ai","mt","tm"]},"languageIds":{"type":"array","description":"The languages the step translates into","items":{"type":"string"}}}}}}}}}}}},"default":{"$ref":"#/components/responses/PlannerFailure"}}}},"/rule-run":{"post":{"summary":"Run Rule","description":"Runs a saved, enabled rule now on every file it matches, with the priorities of the list: Crowdin auto-translates their untranslated strings, and the AI or MT usage is charged. The rules run on their own only for the new strings an event brings; this covers what was there before. Changes the project, confirm with the user first","operationId":"rules.run","tags":["Runs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId","ruleId"],"properties":{"projectId":{"type":"integer"},"ruleId":{"type":"string"}}}}}},"responses":{"200":{"description":"The runs started, one per set of languages","content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/PlannerRun"}}}}}}}}},"default":{"$ref":"#/components/responses/PlannerFailure"}}}},"/runs":{"get":{"summary":"Get Runs","description":"The project's latest 100 runs, newest first. Runs Crowdin is still working on are read again on every call","operationId":"runs.list","tags":["Runs"],"parameters":[{"$ref":"#/components/parameters/PlannerProjectId"}],"responses":{"200":{"description":"The runs","content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/PlannerRun"}}}}}}}}},"default":{"$ref":"#/components/responses/PlannerFailure"}}}},"/run-retry":{"post":{"summary":"Retry Run","description":"Starts again a run that did not start, was skipped, failed or was canceled, on its files and languages with what its rule says now. Changes the project, confirm with the user first","operationId":"runs.retry","tags":["Runs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["projectId","runId"],"properties":{"projectId":{"type":"integer"},"runId":{"type":"string","description":"A run of Get Runs whose canRetry is true"}}}}}},"responses":{"200":{"description":"The run started again","content":{"application/json":{"schema":{"properties":{"data":{"type":"object","properties":{"run":{"$ref":"#/components/schemas/PlannerRun"}}}}}}}},"default":{"$ref":"#/components/responses/PlannerFailure"}}}}},"components":{"parameters":{"PlannerProjectId":{"name":"projectId","in":"query","required":true,"description":"The project, one of this organization's","schema":{"type":"integer"}}},"schemas":{"PlannerVersion":{"type":"string","description":"A fingerprint of the project's settings: any change of the switch, the events or the rules gives a new one. Get Settings and Get Rules return it. Send it back with Update Settings or Update Rules to save only if nobody changed the settings since you read them: otherwise nothing is saved and the answer is 409 SETTINGS_CHANGED, so read again and make the change to what is there now. Without it the save goes over what changed before the call; a change made while the call runs still stops it with 409","example":"3f9a1c0be47d2a85"},"PlannerRule":{"type":"object","properties":{"id":{"type":"string","description":"Left out for a new rule, which then gets one"},"name":{"type":"string","maxLength":100},"enabled":{"type":"boolean","default":true},"patterns":{"type":"array","maxItems":50,"description":"Globs as in crowdin.yml, case-sensitive. Without a slash a file name in any folder (legal.json, *.md), with one a path from the root (/docs/guide.md, /docs/**), with a trailing slash a whole folder (/docs/); ! leaves files out. In a project with branches a path starts after the branch name, or with it to pick one branch. In a string-based project the patterns match branch names","items":{"type":"string"}},"languageIds":{"type":"array","description":"Target languages of the project","items":{"type":"string"}},"method":{"type":"string","enum":["ai","mt","tm"]},"aiPromptId":{"type":"integer","nullable":true,"description":"method ai; a prompt of Get Rule Options"},"engineId":{"type":"integer","nullable":true,"description":"method mt; an engine of Get Rule Options, whose targets take every language of the rule"},"customInstruction":{"type":"string","maxLength":10000,"description":"method ai; appended to the prompt"},"autoApproveOption":{"type":"string","enum":["none","all","exceptAutoSubstituted","perfectMatchOnly","perfectMatchApprovedOnly"],"description":"method tm; which added translations Crowdin approves"},"translateWithPerfectMatchOnly":{"type":"boolean","description":"method tm; perfect matches (the same context too) rather than every 100% match"},"minimumMatchRatio":{"type":"integer","minimum":40,"maximum":100,"description":"method tm on Crowdin Enterprise; the lowest match taken. Always 100 on crowdin.com"},"translateEdited":{"type":"boolean","description":"String-based projects; edited strings start the rule too"}}},"PlannerSettings":{"type":"object","properties":{"enabled":{"type":"boolean"},"events":{"type":"array","description":"The file events that start the rules; a string-based project has none to pick","items":{"type":"string","enum":["file.added","file.updated","file.reverted"]}},"stringBased":{"type":"boolean","description":"Left out when the app was turned off while Crowdin did not tell the project's type"},"webhook":{"type":"string","nullable":true,"enum":["active","inactive","outdated","missing"],"description":"The project's webhook, through which the rules hear of new strings; null while the app is off"},"version":{"$ref":"#/components/schemas/PlannerVersion"}}},"PlannerRun":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"trigger":{"description":"The events that started the run, or manual","oneOf":[{"type":"array","items":{"type":"string"}},{"type":"string","enum":["manual"]}]},"ruleId":{"type":"string"},"ruleName":{"type":"string"},"method":{"type":"string","enum":["ai","mt","tm"]},"languageIds":{"type":"array","items":{"type":"string"}},"files":{"type":"array","description":"The first 20 files of the run; branches in a string-based project","items":{"type":"object","properties":{"id":{"type":"integer"},"path":{"type":"string"}}}},"fileCount":{"type":"integer"},"status":{"type":"string","enum":["pending","in_progress","finished","failed","canceled","unknown","not_started","skipped"],"description":"finished alone does not mean anything was translated; see results and skipped"},"reason":{"type":"string","description":"Why the run did not start or was skipped"},"results":{"type":"array","items":{"type":"object","properties":{"languageId":{"type":"string"},"phrases":{"type":"integer"},"words":{"type":"integer"}}}},"skipped":{"type":"object","description":"Strings Crowdin left untranslated, by its reason (qa_check, ai_payment_error, mt_engine_error…)","additionalProperties":{"type":"integer"}},"reportPath":{"type":"string","description":"The run's report in Crowdin, a path on the organization's address; empty when there is none"},"canRetry":{"type":"boolean"}}},"PlannerError":{"type":"object","properties":{"data":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"details":{"type":"object","description":"The rule and the field a message is about"}}}}}}}},"responses":{"PlannerFailure":{"description":"The message says what to change. 400 a request it cannot take, 403 the caller does not manage the project (MANAGER_ACCESS_REQUIRED), 404 not found, 409 a conflict, 502 Crowdin failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlannerError"}}}}}},"tags":[]}