feat(API): add automation events list endpoints #STRINGS-2826

main.yaml

@@ -75,6 +75,7 @@ tags:
           </tbody>
         </table>
       </div>
+  - name: Automation Events
   - name: Blacklisted Keys
   - name: Branches
     description: |

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:

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"

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

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

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

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: