diff --git a/doc/compiled.json b/doc/compiled.json index 6e13a88a6..60b384e10 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -46,6 +46,9 @@ "name": "Authorizations", "description": "The endpoints provided by the Authorizations API are **only accessible via Basic authentication with email and password**.\n\nWhen creating a new authorization, the new access token for this authorization will be returned in the immediate response but not later, due to security reasons. When accessing authorizations later, you will only see the last eight chars of the token in plain text (`token_last_eight`) and the SHA256 digest of the token for reference (`hashed_token`).\n\nFor instructions on how authorization in general works, see our [Auth Guide](#overview--authentication).\n\n### Scopes\n\nWhen creating or updating an OAuth authorization, you can define a list of scopes to limit the access that can be performed by that authorization.\n\n#### Available Scopes\n\n
\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n
ScopeDescription
readRead projects, locales, keys, translations, orders
writeWrite projects, locales, keys, translations but not orders
orders.createCreate and confirm orders
team.manageManage invitations and members
\n
\n" }, + { + "name": "Automation Events" + }, { "name": "Blacklisted Keys" }, @@ -5148,6 +5151,91 @@ "created_at": "2021-06-28T09:52:53Z", "updated_at": "2021-06-28T09:52:53Z" } + }, + "automation_event": { + "type": "object", + "title": "automation_event", + "properties": { + "id": { + "type": "string", + "description": "Unique identifier of the automation event." + }, + "automation_id": { + "type": "string", + "description": "Identifier of the automation that produced this event." + }, + "state": { + "type": "string", + "enum": [ + "success", + "failure", + "in_progress" + ], + "description": "Outcome of the automation run." + }, + "triggered_by": { + "type": "string", + "enum": [ + "manual", + "schedule", + "upload", + "upload_batch" + ], + "description": "What caused the automation to run." + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the event was created." + }, + "jobs_created": { + "type": "integer", + "description": "Number of jobs created during this automation run." + }, + "job_ids": { + "type": "array", + "description": "Identifiers of the jobs created during this automation run.", + "items": { + "type": "string" + } + }, + "project": { + "type": "object", + "description": "The project associated with this automation event. Null when no project is set.", + "properties": { + "id": { + "type": "string", + "description": "Project identifier." + }, + "name": { + "type": "string", + "description": "Project name." + } + } + }, + "details": { + "type": "string", + "nullable": true, + "description": "Error message describing the failure when state is `failure`; null otherwise." + } + }, + "example": { + "id": "abcd1234ef56", + "automation_id": "xyz9876abc123", + "state": "success", + "triggered_by": "schedule", + "created_at": "2021-06-28T09:52:53Z", + "jobs_created": 3, + "job_ids": [ + "job1abc", + "job2def" + ], + "project": { + "id": "proj1234abcd", + "name": "My Project" + }, + "details": null + } } }, "parameters": { @@ -5211,6 +5299,15 @@ "type": "string" } }, + "query_automation_id": { + "in": "query", + "name": "automation_id", + "description": "Filter events to a single automation by its ID.", + "required": false, + "schema": { + "type": "string" + } + }, "repo_sync_id": { "in": "path", "name": "repo_sync_id", @@ -5505,7 +5602,7 @@ }, "job_updated_since": { "description": "filter by jobs updated since given date", - "example": "2013-02-21T00:00:00.000Z", + "example": "2013-02-21T00:00:00Z", "name": "updated_since", "in": "query", "schema": { @@ -32573,6 +32670,305 @@ } ] } + }, + "/accounts/{account_id}/automations/{automation_id}/events": { + "get": { + "summary": "List events for an automation", + "description": "Returns the run history for a specific automation, newest-first.\n\nFor feature availability, see [Jobs (Strings)](https://support.phrase.com/hc/en-us/articles/5784100517788-Jobs-Strings).\n", + "operationId": "automation_events/list", + "tags": [ + "Automation Events" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/account_id" + }, + { + "$ref": "#/components/parameters/id" + }, + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/per_page" + }, + { + "name": "state", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "success", + "failure", + "in_progress" + ] + }, + "description": "Filter events by outcome state. Unrecognized values are ignored." + }, + { + "name": "triggered_by", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "manual", + "schedule", + "upload", + "upload_batch" + ] + }, + "description": "Filter events by what triggered the automation run. Unrecognized values are ignored." + }, + { + "name": "project_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter events by project ID. Accepts a single ID or a comma-separated list of IDs." + }, + { + "name": "project_ids", + "in": "query", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": "Filter events by one or more project IDs." + }, + { + "name": "created_after", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "example": "2023-01-01T00:00:00Z", + "description": "Return only events created after this ISO 8601 timestamp. Returns 400 if the value is not a valid date-time." + }, + { + "name": "created_before", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "example": "2023-01-01T00:00:00Z", + "description": "Return only events created before this ISO 8601 timestamp. Returns 400 if the value is not a valid date-time." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/automation_event" + } + } + } + }, + "headers": { + "X-Rate-Limit-Limit": { + "$ref": "#/components/headers/X-Rate-Limit-Limit" + }, + "X-Rate-Limit-Remaining": { + "$ref": "#/components/headers/X-Rate-Limit-Remaining" + }, + "X-Rate-Limit-Reset": { + "$ref": "#/components/headers/X-Rate-Limit-Reset" + }, + "Link": { + "$ref": "#/components/headers/Link" + }, + "Pagination": { + "$ref": "#/components/headers/Pagination" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403", + "description": "Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to read this automation, or when the account does not have the Automation Job Creation feature." + }, + "404": { + "$ref": "#/components/responses/404" + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "x-code-samples": [ + { + "lang": "Curl", + "source": "curl \"https://api.phrase.com/v2/accounts/:account_id/automations/:id/events\" \\\n -u USERNAME_OR_ACCESS_TOKEN" + } + ] + } + }, + "/accounts/{account_id}/automation_events": { + "get": { + "summary": "List automation events for an account", + "description": "Returns the run history across all automations in the account, newest-first.\n\nUse `automation_id` to narrow results to a single automation. Use `project_id` or `project_ids` to narrow by project.\n\nFor feature availability, see [Jobs (Strings)](https://support.phrase.com/hc/en-us/articles/5784100517788-Jobs-Strings).\n", + "operationId": "account_automation_events/list", + "tags": [ + "Automation Events" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/account_id" + }, + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/per_page" + }, + { + "$ref": "#/components/parameters/query_automation_id" + }, + { + "name": "state", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "success", + "failure", + "in_progress" + ] + }, + "description": "Filter events by outcome state. Unrecognized values are ignored." + }, + { + "name": "triggered_by", + "in": "query", + "required": false, + "schema": { + "type": "string", + "enum": [ + "manual", + "schedule", + "upload", + "upload_batch" + ] + }, + "description": "Filter events by what triggered the automation run. Unrecognized values are ignored." + }, + { + "name": "project_id", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Filter events by project ID. Accepts a single ID or a comma-separated list of IDs." + }, + { + "name": "project_ids", + "in": "query", + "required": false, + "schema": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": "Filter events by one or more project IDs." + }, + { + "name": "created_after", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "example": "2023-01-01T00:00:00Z", + "description": "Return only events created after this ISO 8601 timestamp. Returns 400 if the value is not a valid date-time." + }, + { + "name": "created_before", + "in": "query", + "required": false, + "schema": { + "type": "string" + }, + "example": "2023-01-01T00:00:00Z", + "description": "Return only events created before this ISO 8601 timestamp. Returns 400 if the value is not a valid date-time." + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/automation_event" + } + } + } + }, + "headers": { + "X-Rate-Limit-Limit": { + "$ref": "#/components/headers/X-Rate-Limit-Limit" + }, + "X-Rate-Limit-Remaining": { + "$ref": "#/components/headers/X-Rate-Limit-Remaining" + }, + "X-Rate-Limit-Reset": { + "$ref": "#/components/headers/X-Rate-Limit-Reset" + }, + "Link": { + "$ref": "#/components/headers/Link" + }, + "Pagination": { + "$ref": "#/components/headers/Pagination" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403", + "description": "Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to list automations in this account, or when the account does not have the Automation Job Creation feature." + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "x-code-samples": [ + { + "lang": "Curl", + "source": "curl \"https://api.phrase.com/v2/accounts/:account_id/automation_events\" \\\n -u USERNAME_OR_ACCESS_TOKEN" + } + ] + } } } } diff --git a/main.yaml b/main.yaml index e6448e767..7c2728472 100644 --- a/main.yaml +++ b/main.yaml @@ -75,6 +75,7 @@ tags: + - name: Automation Events - name: Blacklisted Keys - name: Branches description: | diff --git a/parameters.yaml b/parameters.yaml index c9cf0eed6..dfb94468f 100644 --- a/parameters.yaml +++ b/parameters.yaml @@ -46,6 +46,13 @@ query_account_id: required: false schema: type: string +query_automation_id: + in: query + name: automation_id + description: Filter events to a single automation by its ID. + required: false + schema: + type: string repo_sync_id: in: path name: repo_sync_id @@ -290,7 +297,7 @@ job_state: type: string job_updated_since: description: filter by jobs updated since given date - example: 2013-02-21T00:00:00Z + example: "2013-02-21T00:00:00Z" name: updated_since in: query schema: diff --git a/paths.yaml b/paths.yaml index 645fb6844..8cd0e974c 100644 --- a/paths.yaml +++ b/paths.yaml @@ -756,3 +756,9 @@ "/accounts/{account_id}/automations/{automation_id}/trigger": post: "$ref": "./paths/automations/trigger.yaml" +"/accounts/{account_id}/automations/{automation_id}/events": + get: + "$ref": "./paths/automations/events.yaml" +"/accounts/{account_id}/automation_events": + get: + "$ref": "./paths/automation_events/index.yaml" diff --git a/paths/automation_events/index.yaml b/paths/automation_events/index.yaml new file mode 100644 index 000000000..cf67f03c6 --- /dev/null +++ b/paths/automation_events/index.yaml @@ -0,0 +1,100 @@ +--- +summary: List automation events for an account +description: | + Returns the run history across all automations in the account, newest-first. + + Use `automation_id` to narrow results to a single automation. Use `project_id` or `project_ids` to narrow by project. + + For feature availability, see [Jobs (Strings)](https://support.phrase.com/hc/en-us/articles/5784100517788-Jobs-Strings). +operationId: account_automation_events/list +tags: +- Automation Events +parameters: +- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" +- "$ref": "../../parameters.yaml#/account_id" +- "$ref": "../../parameters.yaml#/page" +- "$ref": "../../parameters.yaml#/per_page" +- "$ref": "../../parameters.yaml#/query_automation_id" +- name: state + in: query + required: false + schema: + type: string + enum: + - success + - failure + - in_progress + description: Filter events by outcome state. Unrecognized values are ignored. +- name: triggered_by + in: query + required: false + schema: + type: string + enum: + - manual + - schedule + - upload + - upload_batch + description: Filter events by what triggered the automation run. Unrecognized values are ignored. +- name: project_id + in: query + required: false + schema: + type: string + description: Filter events by project ID. Accepts a single ID or a comma-separated list of IDs. +- name: project_ids + in: query + required: false + schema: + type: array + items: + type: string + description: Filter events by one or more project IDs. +- name: created_after + in: query + required: false + schema: + type: string + example: "2023-01-01T00:00:00Z" + description: Return only events created after this ISO 8601 timestamp. Returns 400 if the value is not a valid date-time. +- name: created_before + in: query + required: false + schema: + type: string + example: "2023-01-01T00:00:00Z" + description: Return only events created before this ISO 8601 timestamp. Returns 400 if the value is not a valid date-time. +responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + "$ref": "../../schemas/automation_event.yaml#/automation_event" + headers: + X-Rate-Limit-Limit: + "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" + X-Rate-Limit-Remaining: + "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" + X-Rate-Limit-Reset: + "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + Link: + "$ref": "../../headers.yaml#/Link" + Pagination: + "$ref": "../../headers.yaml#/Pagination" + '400': + "$ref": "../../responses.yaml#/400" + '401': + "$ref": "../../responses.yaml#/401" + '403': + "$ref": "../../responses.yaml#/403" + description: Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to list automations in this account, or when the account does not have the Automation Job Creation feature. + '429': + "$ref": "../../responses.yaml#/429" +x-code-samples: +- lang: Curl + source: |- + curl "https://api.phrase.com/v2/accounts/:account_id/automation_events" \ + -u USERNAME_OR_ACCESS_TOKEN diff --git a/paths/automations/events.yaml b/paths/automations/events.yaml new file mode 100644 index 000000000..6af361dee --- /dev/null +++ b/paths/automations/events.yaml @@ -0,0 +1,100 @@ +--- +summary: List events for an automation +description: | + Returns the run history for a specific automation, newest-first. + + For feature availability, see [Jobs (Strings)](https://support.phrase.com/hc/en-us/articles/5784100517788-Jobs-Strings). +operationId: automation_events/list +tags: +- Automation Events +parameters: +- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" +- "$ref": "../../parameters.yaml#/account_id" +- "$ref": "../../parameters.yaml#/id" +- "$ref": "../../parameters.yaml#/page" +- "$ref": "../../parameters.yaml#/per_page" +- name: state + in: query + required: false + schema: + type: string + enum: + - success + - failure + - in_progress + description: Filter events by outcome state. Unrecognized values are ignored. +- name: triggered_by + in: query + required: false + schema: + type: string + enum: + - manual + - schedule + - upload + - upload_batch + description: Filter events by what triggered the automation run. Unrecognized values are ignored. +- name: project_id + in: query + required: false + schema: + type: string + description: Filter events by project ID. Accepts a single ID or a comma-separated list of IDs. +- name: project_ids + in: query + required: false + schema: + type: array + items: + type: string + description: Filter events by one or more project IDs. +- name: created_after + in: query + required: false + schema: + type: string + example: "2023-01-01T00:00:00Z" + description: Return only events created after this ISO 8601 timestamp. Returns 400 if the value is not a valid date-time. +- name: created_before + in: query + required: false + schema: + type: string + example: "2023-01-01T00:00:00Z" + description: Return only events created before this ISO 8601 timestamp. Returns 400 if the value is not a valid date-time. +responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + "$ref": "../../schemas/automation_event.yaml#/automation_event" + headers: + X-Rate-Limit-Limit: + "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" + X-Rate-Limit-Remaining: + "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" + X-Rate-Limit-Reset: + "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + Link: + "$ref": "../../headers.yaml#/Link" + Pagination: + "$ref": "../../headers.yaml#/Pagination" + '400': + "$ref": "../../responses.yaml#/400" + '401': + "$ref": "../../responses.yaml#/401" + '403': + "$ref": "../../responses.yaml#/403" + description: Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to read this automation, or when the account does not have the Automation Job Creation feature. + '404': + "$ref": "../../responses.yaml#/404" + '429': + "$ref": "../../responses.yaml#/429" +x-code-samples: +- lang: Curl + source: |- + curl "https://api.phrase.com/v2/accounts/:account_id/automations/:id/events" \ + -u USERNAME_OR_ACCESS_TOKEN diff --git a/schemas.yaml b/schemas.yaml index b7c4a2e27..a1584bf05 100644 --- a/schemas.yaml +++ b/schemas.yaml @@ -176,3 +176,5 @@ schemas: "$ref": schemas/repo_sync_event.yaml#/repo_sync_event automation: "$ref": schemas/automation.yaml#/automation + automation_event: + "$ref": schemas/automation_event.yaml#/automation_event diff --git a/schemas/automation_event.yaml b/schemas/automation_event.yaml new file mode 100644 index 000000000..29a9e1e48 --- /dev/null +++ b/schemas/automation_event.yaml @@ -0,0 +1,59 @@ +--- +automation_event: + type: object + title: automation_event + properties: + id: + type: string + description: Unique identifier of the automation event. + automation_id: + type: string + description: Identifier of the automation that produced this event. + state: + type: string + enum: [success, failure, in_progress] + description: Outcome of the automation run. + triggered_by: + type: string + enum: [manual, schedule, upload, upload_batch] + description: What caused the automation to run. + created_at: + type: string + format: date-time + description: Timestamp when the event was created. + jobs_created: + type: integer + description: Number of jobs created during this automation run. + job_ids: + type: array + description: Identifiers of the jobs created during this automation run. + items: + type: string + project: + type: object + description: The project associated with this automation event. Null when no project is set. + properties: + id: + type: string + description: Project identifier. + name: + type: string + description: Project name. + details: + type: string + nullable: true + description: Error message describing the failure when state is `failure`; null otherwise. + example: + id: abcd1234ef56 + automation_id: xyz9876abc123 + state: success + triggered_by: schedule + created_at: '2021-06-28T09:52:53Z' + jobs_created: 3 + job_ids: + - job1abc + - job2def + project: + id: proj1234abcd + name: My Project + details: