Incident.io Actions V1 API

openapi: 3.2.0
info:
  description: 'This is the API reference for incident.io. It documents available API endpoints, provides examples of how to use it, and

    instructions around things like authentication and error handling. The API is hosted at:


    - https://api.incident.io/


    And you will need to create an API key via your incident.io

    dashboard to make requests. # Making requests


    Here are the key concepts required to make requests to the incident.io API. ## Authentication


    For all requests made to the incident.io API, you''ll need an API key. To create an API key, head to the incident dashboard and visit API

    keys. When you create the key, you''ll be able to choose what actions it

    can take for your account: choose carefully, as those roles can only be set

    when you first create the key. We''ll only show you the token once, so make sure

    you store it somewhere safe. API keys are global to your incident.io account, and can be managed by anyone

    who has the right permissions. We display the user that created the API key,

    and the API key will remain valid if that user becomes deactivated. Once you have the key, you should make requests to the API that set the

    `Authorization` request header using a "Bearer" authentication scheme:


    ```

    Authorization: Bearer

    ```


    ## Rate Limits


    The incident.io API enforces rate limits to ensure consistent performance for all users. The default rate limit is 1200 requests/minute per API key. This limit applies to most endpoints across the API. Limits are token buckets that refill continuously rather than resetting on a fixed window boundary. The default

    bucket holds 1200 requests and refills at 20 per second, so you can burst up to the full bucket and then sustain

    20 requests/second indefinitely. There is no boundary at which your quota resets to full in one step. Some endpoints have lower rate limits, particularly those that interact with external third-party systems that impose

    their own limitations. These specific limits vary by endpoint. ### Rate limit headers


    Responses to requests authenticated with an API key carry your current allowance, so you can pace yourself rather

    than waiting to be throttled:


    ```

    X-RateLimit-Limit: 60, 1200;window=60, 60;window=60

    X-RateLimit-Remaining: 59

    X-RateLimit-Used: 1

    X-RateLimit-Reset: 1785173199

    ```


    | Header | Meaning |

    | --- | --- |

    | `X-RateLimit-Limit` | The quota that binds this request, followed by every limit that applied and the window it applies over |

    | `X-RateLimit-Remaining` | Requests you can make right now against the binding limit |

    | `X-RateLimit-Used` | Requests you have spent against it |

    | `X-RateLimit-Reset` | Unix timestamp (seconds) at which that limit will be back to full |


    More than one limit can apply to a request: your API key''s overall limit, and for some endpoints a lower limit of

    their own. `X-RateLimit-Limit` lists all of them, each with its window, so `1200;window=60` means 1200 requests per

    minute. Because our limits refill continuously rather than resetting on a boundary, that window is what tells you

    the rate you can sustain: 1200 per 60 seconds is 20 requests/second indefinitely. `Remaining`, `Used` and `Reset` describe whichever limit has the least allowance left, since that is the one you

    will hit first. `X-RateLimit-Remaining` may lag by a small number of requests under high concurrency, and can move by more than the

    requests you made, because limits scoped to your whole organisation are shared with your other API keys. Headers are omitted rather than guessed if we cannot determine your allowance for a request. ### Exceeding a rate limit


    When you exceed a rate limit the API responds with `429 Too Many Requests` and a `Retry-After` header giving the

    number of seconds to wait:


    ```

    X-RateLimit-Limit: 1200, 1200;window=60

    X-RateLimit-Remaining: 0

    X-RateLimit-Used: 1200

    X-RateLimit-Reset: 1785173199

    Retry-After: 1

    ```


    Prefer `Retry-After` over `X-RateLimit-Reset` when deciding how long to back off.'
  title: incident.io Actions V1 API
  version: 1.0.0
servers:
- url: https://api.incident.io
security:
- BearerAuth: []
tags:
- description: 'Manage incident actions.


    These endpoints have been deprecated in favour of Actions V2 and Follow-ups V2, as these

    concepts have become increasingly separate.


    Incidents have two types of actions associated to them:


    - Actions, used during an incident response as ephemeral todo lists

    - Follow-ups, actions which are for after the incident and can be exported to external

    issue trackers


    You can manage actions in the incident Slack channel with /incident actions, or on

    the incident homepage.


    Exporting follow-ups to external issue trackers can be done in the incident homepage.'
  name: Actions V1
paths:
  /v1/actions:
    get:
      deprecated: true
      description: List all actions for an organisation.
      operationId: ActionsV1#List
      parameters:
      - allowEmptyValue: true
        description: Find actions related to this incident
        example: 01FCNDV6P870EA6S7TK1DSYDG0
        in: query
        name: incident_id
        schema:
          example: 01FCNDV6P870EA6S7TK1DSYD5H
          type: string
      - allowEmptyValue: true
        description: Filter to actions marked as being follow up actions
        example: true
        in: query
        name: is_follow_up
        schema:
          description: Filter to actions marked as being follow up actions
          example: true
          type: boolean
      - allowEmptyValue: true
        description: Filter to actions from incidents of the given mode. If not set, only actions from `real` incidents are returned
        examples:
          default:
            summary: default
            value: real
        in: query
        name: incident_mode
        schema:
          description: Filter to actions from incidents of the given mode. If not set, only actions from `real` incidents are returned
          enum:
          - real
          - test
          - tutorial
          example: real
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                actions:
                - assignee:
                    email: lisa@incident.io
                    id: 01FCNDV6P870EA6S7TK1DSYDG0
                    name: Lisa Karlin Curtis
                    role: viewer
                    slack_user_id: U02AYNF2XJM
                  completed_at: '2021-08-17T13:28:57.801578Z'
                  created_at: '2021-08-17T13:28:57.801578Z'
                  description: Call the fire brigade
                  external_issue_reference:
                    issue_name: INC-123
                    issue_permalink: https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up
                    provider: asana
                  follow_up: true
                  id: 01FCNDV6P870EA6S7TK1DSYDG0
                  incident_id: 01FCNDV6P870EA6S7TK1DSYDG0
                  status: outstanding
                  updated_at: '2021-08-17T13:28:57.801578Z'
              schema:
                $ref: '#/components/schemas/ActionsListResultV1'
          description: OK response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn''t exist.'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'authentication_error: Authentication failed.'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'resource_forbidden: Access to this resource is forbidden for the authenticated user.'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'not_found: The referenced resource could not be found.'
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'method_not_allowed: The endpoint does not support this operation for the specified resource.'
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'not_acceptable: Requested a media type this endpoint does not support.'
        '408':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'request_timeout: The request took too long to process.


            client_timeout: The request was cancelled by the client.'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'conflict: Request conflicted with current state of the resource, likely a concurrent update.'
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'precondition_failed: A required condition hasn''t been met.'
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'payload_too_large: The request payload is too large.'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'validation_error: A required field was not provided, or the provided data was invalid.'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.


            rate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later.'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'api_error: Something went wrong and has been reported internally.'
      summary: List Actions V1
      tags:
      - Actions V1
      x-docs-display-name: List
      x-docs-group-name: Actions V1
      x-docs-resource-type: ActionV1
      x-mint:
        content: 🔑 Requires the `actions.view` scope.
      x-rbac-scopes:
      - actions.view
      x-operation-id-source: normalized
      x-operation-id-original: Actions V1#List
  /v1/actions/{id}:
    get:
      deprecated: true
      description: Get a single incident action.
      operationId: ActionsV1#Show
      parameters:
      - description: Unique identifier for the action
        examples:
          default:
            summary: default
            value: 01FCNDV6P870EA6S7TK1DSYDG0
        in: path
        name: id
        required: true
        schema:
          example: 01FCNDV6P870EA6S7TK1DSYD5H
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                action:
                  assignee:
                    email: lisa@incident.io
                    id: 01FCNDV6P870EA6S7TK1DSYDG0
                    name: Lisa Karlin Curtis
                    role: viewer
                    slack_user_id: U02AYNF2XJM
                  completed_at: '2021-08-17T13:28:57.801578Z'
                  created_at: '2021-08-17T13:28:57.801578Z'
                  description: Call the fire brigade
                  external_issue_reference:
                    issue_name: INC-123
                    issue_permalink: https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up
                    provider: asana
                  follow_up: true
                  id: 01FCNDV6P870EA6S7TK1DSYDG0
                  incident_id: 01FCNDV6P870EA6S7TK1DSYDG0
                  status: outstanding
                  updated_at: '2021-08-17T13:28:57.801578Z'
              schema:
                $ref: '#/components/schemas/ActionsShowResultV1'
          description: OK response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'invalid_request_error: There was a problem with the request, like a missing header or querying a resource that doesn''t exist.'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'authentication_error: Authentication failed.'
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'resource_forbidden: Access to this resource is forbidden for the authenticated user.'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'not_found: The referenced resource could not be found.'
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'method_not_allowed: The endpoint does not support this operation for the specified resource.'
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'not_acceptable: Requested a media type this endpoint does not support.'
        '408':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'request_timeout: The request took too long to process.


            client_timeout: The request was cancelled by the client.'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'conflict: Request conflicted with current state of the resource, likely a concurrent update.'
        '412':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'precondition_failed: A required condition hasn''t been met.'
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'payload_too_large: The request payload is too large.'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'validation_error: A required field was not provided, or the provided data was invalid.'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'too_many_requests: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.


            rate_limit_reached: The rate limit associated with this resource or API key has been exceeded. Try again later.'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: 'api_error: Something went wrong and has been reported internally.'
      summary: Show Actions V1
      tags:
      - Actions V1
      x-docs-display-name: Show
      x-docs-group-name: Actions V1
      x-docs-resource-type: ActionV1
      x-mint:
        content: 🔑 Requires the `actions.view` scope.
      x-rbac-scopes:
      - actions.view
      x-operation-id-source: normalized
      x-operation-id-original: Actions V1#Show
components:
  schemas:
    ErrorRateLimit:
      example:
        limit: 100
        name: client_ip
        remaining: 98
        retry_after: '2020-01-01T00:00:00Z'
      properties:
        limit:
          description: The maximum number of requests that the consumer is permitted to make per minute
          example: 100
          format: int64
          type: integer
        name:
          description: Which rate limit was exceeded
          example: client_ip
          type: string
        remaining:
          description: The number of requests remaining in the current rate limit window
          example: 98
          format: int64
          type: integer
        retry_after:
          description: When the client can retry, as an RFC3339 timestamp in UTC. Prefer the Retry-After response header, which carries the same instant as a number of seconds
          example: '2020-01-01T00:00:00Z'
          type: string
      required:
      - name
      - limit
      - remaining
      - retry_after
      type: object
    ErrorResponse:
      example:
        debug:
          message: 'Something broke: and something else: and something else'
          stacktrace:
          - thing.go:123
        errors:
        - code: trial_expired
          message: Default incident call link must be a valid URL
          metadata:
            abc123: abc123
          source:
            field: default_call_url
            pointer: /settings/default_call_url
        rate_limit:
          limit: 100
          name: client_ip
          remaining: 98
          retry_after: '2020-01-01T00:00:00Z'
        request_id: 2T1p0e3j
        status: 408
        type: invalid_request_error
      properties:
        debug:
          $ref: '#/components/schemas/ErrorDebug'
        errors:
          description: List of errors that caused this request to fail
          example:
          - code: trial_expired
            message: Default incident call link must be a valid URL
            metadata:
              abc123: abc123
            source:
              field: default_call_url
              pointer: /settings/default_call_url
          items:
            $ref: '#/components/schemas/ErrorSingle'
          type: array
        rate_limit:
          $ref: '#/components/schemas/ErrorRateLimit'
        request_id:
          description: Unique identifier of the request
          example: 2T1p0e3j
          type: string
        status:
          description: HTTP status of the response
          example: 408
          format: int64
          type: integer
        type:
          description: Machine-readable identifier for the general category of error
          enum:
          - invalid_request_error
          - authentication_error
          - resource_forbidden
          - not_found
          - not_acceptable
          - method_not_allowed
          - request_timeout
          - conflict
          - precondition_failed
          - payload_too_large
          - validation_error
          - too_many_requests
          - api_error
          - rate_limit_reached
          - client_timeout
          example: invalid_request_error
          type: string
      required:
      - type
      - status
      - request_id
      - errors
      type: object
    ErrorDebug:
      example:
        message: 'Something broke: and something else: and something else'
        stacktrace:
        - thing.go:123
      properties:
        message:
          description: Original internal error message
          example: 'Something broke: and something else: and something else'
          type: string
        stacktrace:
          description: Stacktrace of the error, if applicable
          example:
          - thing.go:123
          items:
            example: thing.go:123
            type: string
          type: array
      required:
      - message
      - stacktrace
      type: object
    ActionsListResultV1:
      example:
        actions:
        - assignee:
            email: lisa@incident.io
            id: 01FCNDV6P870EA6S7TK1DSYDG0
            name: Lisa Karlin Curtis
            role: viewer
            slack_user_id: U02AYNF2XJM
          completed_at: '2021-08-17T13:28:57.801578Z'
          created_at: '2021-08-17T13:28:57.801578Z'
          description: Call the fire brigade
          external_issue_reference:
            issue_name: INC-123
            issue_permalink: https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up
            provider: asana
          follow_up: true
          id: 01FCNDV6P870EA6S7TK1DSYDG0
          incident_id: 01FCNDV6P870EA6S7TK1DSYDG0
          status: outstanding
          updated_at: '2021-08-17T13:28:57.801578Z'
      properties:
        actions:
          example:
          - assignee:
              email: lisa@incident.io
              id: 01FCNDV6P870EA6S7TK1DSYDG0
              name: Lisa Karlin Curtis
              role: viewer
              slack_user_id: U02AYNF2XJM
            completed_at: '2021-08-17T13:28:57.801578Z'
            created_at: '2021-08-17T13:28:57.801578Z'
            description: Call the fire brigade
            external_issue_reference:
              issue_name: INC-123
              issue_permalink: https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up
              provider: asana
            follow_up: true
            id: 01FCNDV6P870EA6S7TK1DSYDG0
            incident_id: 01FCNDV6P870EA6S7TK1DSYDG0
            status: outstanding
            updated_at: '2021-08-17T13:28:57.801578Z'
          items:
            $ref: '#/components/schemas/ActionV1'
          type: array
      required:
      - actions
      type: object
    ActionV1:
      example:
        assignee:
          email: lisa@incident.io
          id: 01FCNDV6P870EA6S7TK1DSYDG0
          name: Lisa Karlin Curtis
          role: viewer
          slack_user_id: U02AYNF2XJM
        completed_at: '2021-08-17T13:28:57.801578Z'
        created_at: '2021-08-17T13:28:57.801578Z'
        description: Call the fire brigade
        external_issue_reference:
          issue_name: INC-123
          issue_permalink: https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up
          provider: asana
        follow_up: true
        id: 01FCNDV6P870EA6S7TK1DSYDG0
        incident_id: 01FCNDV6P870EA6S7TK1DSYDG0
        status: outstanding
        updated_at: '2021-08-17T13:28:57.801578Z'
      properties:
        assignee:
          $ref: '#/components/schemas/UserV1'
        completed_at:
          description: When the action was completed
          example: '2021-08-17T13:28:57.801578Z'
          format: date-time
          type: string
        created_at:
          description: When the action was created
          example: '2021-08-17T13:28:57.801578Z'
          format: date-time
          type: string
        description:
          description: Description of the action
          example: Call the fire brigade
          type: string
        external_issue_reference:
          $ref: '#/components/schemas/ExternalIssueReferenceV1'
        follow_up:
          description: Whether an action is marked as follow-up
          example: true
          type: boolean
        id:
          description: Unique identifier for the action
          example: 01FCNDV6P870EA6S7TK1DSYDG0
          type: string
        incident_id:
          description: Unique identifier of the incident the action belongs to
          example: 01FCNDV6P870EA6S7TK1DSYDG0
          type: string
        status:
          description: Status of the action
          enum:
          - outstanding
          - completed
          - deleted
          - not_doing
          example: outstanding
          type: string
        updated_at:
          description: When the action was last updated
          example: '2021-08-17T13:28:57.801578Z'
          format: date-time
          type: string
      required:
      - id
      - incident_id
      - status
      - follow_up
      - created_at
      - updated_at
      type: object
    ActionsShowResultV1:
      example:
        action:
          assignee:
            email: lisa@incident.io
            id: 01FCNDV6P870EA6S7TK1DSYDG0
            name: Lisa Karlin Curtis
            role: viewer
            slack_user_id: U02AYNF2XJM
          completed_at: '2021-08-17T13:28:57.801578Z'
          created_at: '2021-08-17T13:28:57.801578Z'
          description: Call the fire brigade
          external_issue_reference:
            issue_name: INC-123
            issue_permalink: https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up
            provider: asana
          follow_up: true
          id: 01FCNDV6P870EA6S7TK1DSYDG0
          incident_id: 01FCNDV6P870EA6S7TK1DSYDG0
          status: outstanding
          updated_at: '2021-08-17T13:28:57.801578Z'
      properties:
        action:
          $ref: '#/components/schemas/ActionV1'
      required:
      - action
      type: object
    ErrorSingle:
      example:
        code: trial_expired
        message: Default incident call link must be a valid URL
        metadata:
          abc123: abc123
        source:
          field: default_call_url
          pointer: /settings/default_call_url
      properties:
        code:
          description: Machine-readable identifier for this specific error
          example: trial_expired
          type: string
        message:
          description: Human readable description of the error
          example: Default incident call link must be a valid URL
          type: string
        metadata:
          additionalProperties:
            example: abc123
            type: string
          description: Additional metadata about the error, keyed by a string identifier
          example:
            abc123: abc123
          type: object
        source:
          $ref: '#/components/schemas/ErrorSource'
      required:
      - code
      - message
      type: object
    ErrorSource:
      example:
        field: default_call_url
        pointer: /settings/default_call_url
      properties:
        field:
          description: Field name that is the source of the error
          example: default_call_url
          type: string
        pointer:
          description: JSON pointer to the request field that is the source of the error
          example: /settings/default_call_url
          type: string
      required:
      - field
      - pointer
      type: object
    ExternalIssueReferenceV1:
      example:
        issue_name: INC-123
        issue_permalink: https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up
        provider: asana
      properties:
        issue_name:
          description: Human readable ID for the issue
          example: INC-123
          type: string
        issue_permalink:
          description: URL linking directly to the action in the issue tracker
          example: https://linear.app/incident-io/issue/INC-1609/find-copywriter-to-write-up
          type: string
        provider:
          description: ID of the issue tracker provider
          enum:
          - asana
          - azure_devops
          - click_up
          - freshservice
          - linear
          - jira
          - salesforce
          - jira_server
          - github
          - gitlab
          - service_now
          - shortcut
          - notion
          example: asana
          type: string
      type: object
    UserV1:
      example:
        email: lisa@incident.io
        id: 01FCNDV6P870EA6S7TK1DSYDG0
        name: Lisa Karlin Curtis
        role: viewer
        slack_user_id: U02AYNF2XJM
      properties:
        email:
          description: Email address of the user.
          example: lisa@incident.io
          type: string
        id:
          description: Unique identifier of the user
          example: 01FCNDV6P870EA6S7TK1DSYDG0
          type: string
        name:
          description: Name of the user
          example: Lisa Karlin Curtis
          type: string
        role:
          description: 'DEPRECATED: Role of the user as of March 9th 2023, this value is no longer updated.'
          enum:
          - viewer
          - responder
          - administrator
          - owner
          - unset
          example: viewer
          type: string
        slack_user_id:
          description: Slack ID of the user
          example: U02AYNF2XJM
          type: string
      required:
      - role
      - id
      - name
      type: object
  securitySchemes:
    BearerAuth:
      description: API key from your incident.io dashboard (Settings > API keys)
      scheme: bearer
      type: http
externalDocs:
  description: View our API docs at api-docs.incident.io
  url: https://api-docs.incident.io/
x-provenance:
  method: harvested
  publisher: Incident.io
  source: https://api.incident.io/v1/openapiV3.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)