@celigo/api-specs 0.2.1

package/dist/state.yml

@@ -0,0 +1,894 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: State
+  description: API for the Celigo key-value state store — persists JSON objects or arrays across flow runs, globally or per resource.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: State
+    description: |-
+      Key-value state store for persisting JSON objects or arrays across flow
+      runs. Common use cases include tracking sequence numbers, storing cursors
+      for delta syncs, caching lookup values, and passing state between runs.
+
+      **Lookup Caches are now the preferred mechanism** for storing and
+      retrieving data during flow execution. Prefer Lookup Caches for new
+      integrations; State remains supported for existing flows.
+
+      State supports two scopes:
+
+      - **Global** — account-wide keys visible to all flows and scripts.
+      - **Resource-scoped** — keys namespaced under a specific export, import,
+        or integration. Resource-scoped keys are isolated from the global
+        key listing.
+
+      Values must be non-empty JSON objects or arrays. Bare primitives,
+      `null`, and empty containers (`{}`, `[]`) are rejected.
+
+      Prefer resource-scoped state over global state when the data belongs
+      to a specific export, import, or integration. State keys are upserted —
+      PUT creates if absent, replaces if present. There is no PATCH; send the
+      full value each time.
+
+      ## State schema
+
+      {% openapi-schemas spec="state" schemas="State" grouped="true" %}
+paths:
+  /v1/state:
+    get:
+      x-internal: false
+      operationId: listGlobalStateKeys
+      tags:
+        - State
+      summary: List global state keys
+      description: |-
+        Returns all global state key names. Does not return resource-scoped
+        keys — use `GET /v1/{resourceType}/{_id}/state` for those.
+
+        Lists key names only, not values. Call `GET /v1/state/{key}` to
+        retrieve a specific value.
+      responses:
+        '200':
+          description: Object containing an array of key names.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - keys
+                properties:
+                  keys:
+                    type: array
+                    items:
+                      type: string
+              example:
+                keys:
+                  - sequence_number
+                  - last_sync_time
+        '204':
+          description: No global state keys exist.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    delete:
+      x-internal: false
+      operationId: deleteAllGlobalState
+      tags:
+        - State
+      summary: Delete all global state keys
+      description: |-
+        Deletes **all** global state keys and their values. This is a
+        destructive operation and cannot be undone.
+
+        Prefer `DELETE /v1/state/{key}` to remove individual keys.
+      responses:
+        '204':
+          description: All global state deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/state/{key}:
+    get:
+      x-internal: false
+      operationId: getGlobalStateValue
+      tags:
+        - State
+      summary: Get a global state value
+      description: |-
+        Returns the JSON value stored under the given global key.
+
+        Returns the raw JSON value (object or array), not wrapped in an envelope.
+      parameters:
+        - name: key
+          in: path
+          required: true
+          schema:
+            type: string
+            examples:
+              - sequence_number
+          description: The state key name.
+      responses:
+        '200':
+          description: The stored value (a JSON object or array).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/State'
+              examples:
+                object:
+                  summary: Object value
+                  value:
+                    lastSyncTime: '2025-08-10T14:22:33.000Z'
+                    sequenceNumber: 4207
+                array:
+                  summary: Array value
+                  value:
+                    - sku: WIDGET-100
+                      price: 29.99
+                    - sku: WIDGET-200
+                      price: 49.99
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The key does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - message: State not found for key.
+    put:
+      x-internal: false
+      operationId: setGlobalStateValue
+      tags:
+        - State
+      summary: Create or update a global state value
+      description: |-
+        Sets the value for a global state key. Creates the key if it does
+        not exist; replaces the value if it does.
+
+        The request body must be a non-empty JSON object or array. Bare
+        JSON primitives (strings, numbers, booleans, `null`) and empty
+        containers (`{}`, `[]`) are rejected.
+
+        This is an upsert — check the status code to distinguish create (201)
+        from update (200). The response body is plain text, not JSON. If the
+        state belongs to a specific export, import, or integration, use the
+        resource-scoped endpoint instead.
+      parameters:
+        - name: key
+          in: path
+          required: true
+          schema:
+            type: string
+            examples:
+              - sequence_number
+          description: The state key name.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              description: |-
+                A non-empty JSON object or array to store. Bare primitives
+                and empty containers are not accepted.
+              $ref: '#/components/schemas/State'
+            examples:
+              object:
+                summary: Store an object
+                value:
+                  lastSyncTime: '2025-08-10T14:22:33.000Z'
+                  sequenceNumber: 4207
+              array:
+                summary: Store an array
+                value:
+                  - sku: WIDGET-100
+                    price: 29.99
+                  - sku: WIDGET-200
+                    price: 49.99
+      responses:
+        '200':
+          description: Existing key updated.
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - OK
+                x-enumDescriptions:
+                  OK: The existing key was updated successfully.
+        '201':
+          description: New key created.
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - Created
+                x-enumDescriptions:
+                  Created: A new key was created successfully.
+        '400':
+          description: |-
+            Invalid request body. The body is not valid JSON, or is a bare
+            primitive (string, number, boolean, or `null`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - message: Unexpected token '"', ""just a string"" is not valid JSON
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '415':
+          description: |-
+            The `Content-Type` header is missing or is not
+            `application/json`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - message: Content-Type should equal application/json
+        '422':
+          description: |-
+            The request body is empty, or is an empty container (`{}` or
+            `[]`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: missing_request_body
+                    message: Please send state as request body in the PUT request.
+    delete:
+      x-internal: false
+      operationId: deleteGlobalStateKey
+      tags:
+        - State
+      summary: Delete a global state key
+      description: |-
+        Deletes a specific global state key and its value. Returns `404`
+        if the key does not exist.
+      parameters:
+        - name: key
+          in: path
+          required: true
+          schema:
+            type: string
+            examples:
+              - sequence_number
+          description: The state key name.
+      responses:
+        '204':
+          description: Key deleted.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          description: The key does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - message: State not found for key.
+  /v1/{resourceType}/{_resourceId}/state:
+    get:
+      x-internal: false
+      operationId: listResourceStateKeys
+      tags:
+        - State
+      summary: List state keys for a resource
+      description: |-
+        Returns the list of state key names stored under the specified
+        resource. These keys are separate from global state.
+
+        Returns `204 No Content` when no keys exist for the resource.
+
+        Only `exports`, `imports`, and `integrations` support
+        resource-scoped state. Other resource types return `403`.
+
+        This only lists key names, not values. Call
+        `GET /v1/{resourceType}/{_resourceId}/state/{key}` to retrieve a
+        specific value.
+      parameters:
+        - name: resourceType
+          in: path
+          required: true
+          schema:
+            type: string
+            enum:
+              - exports
+              - imports
+              - integrations
+            x-enumDescriptions:
+              exports: State scoped to a specific export
+              imports: State scoped to a specific import
+              integrations: State scoped to a specific integration
+          description: |-
+            The resource type. Only `exports`, `imports`, and
+            `integrations` are supported.
+        - name: _resourceId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 66a1f2c3b4d5e6f7a8b9c0d1
+          description: The resource ID.
+      responses:
+        '200':
+          description: Object containing an array of key names.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - keys
+                properties:
+                  keys:
+                    type: array
+                    items:
+                      type: string
+              example:
+                keys:
+                  - sequence_number
+                  - last_sync_time
+        '204':
+          description: No state keys exist for this resource.
+        '400':
+          description: The resource ID is not a valid identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: |-
+            The resource type does not support state. Only `exports`,
+            `imports`, and `integrations` are allowed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: State not available for the given model.
+        '404':
+          description: The resource was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: Export not found.
+    delete:
+      x-internal: false
+      operationId: deleteAllResourceState
+      tags:
+        - State
+      summary: Delete all state keys for a resource
+      description: |-
+        Deletes **all** state keys and values stored under the specified
+        resource. This is destructive and cannot be undone.
+
+        Prefer `DELETE /v1/{resourceType}/{_resourceId}/state/{key}` to remove
+        individual keys.
+      parameters:
+        - name: resourceType
+          in: path
+          required: true
+          schema:
+            type: string
+            enum:
+              - exports
+              - imports
+              - integrations
+            x-enumDescriptions:
+              exports: State scoped to a specific export
+              imports: State scoped to a specific import
+              integrations: State scoped to a specific integration
+          description: |-
+            The resource type. Only `exports`, `imports`, and
+            `integrations` are supported.
+        - name: _resourceId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 66a1f2c3b4d5e6f7a8b9c0d1
+          description: The resource ID.
+      responses:
+        '204':
+          description: All resource state deleted.
+        '400':
+          description: The resource ID is not a valid identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The resource type does not support state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: State not available for the given model.
+        '404':
+          description: The resource was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: Export not found.
+  /v1/{resourceType}/{_resourceId}/state/{key}:
+    get:
+      x-internal: false
+      operationId: getResourceStateValue
+      tags:
+        - State
+      summary: Get a resource-scoped state value
+      description: |-
+        Returns the JSON value stored under the given key for a specific
+        resource.
+
+        Only `exports`, `imports`, and `integrations` support
+        resource-scoped state.
+
+        Returns the raw JSON value (object or array), not wrapped in an envelope.
+        A 403 means the resource type doesn't support state, not a permissions
+        issue.
+      parameters:
+        - name: resourceType
+          in: path
+          required: true
+          schema:
+            type: string
+            enum:
+              - exports
+              - imports
+              - integrations
+            x-enumDescriptions:
+              exports: State scoped to a specific export
+              imports: State scoped to a specific import
+              integrations: State scoped to a specific integration
+          description: |-
+            The resource type. Only `exports`, `imports`, and
+            `integrations` are supported.
+        - name: _resourceId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 66a1f2c3b4d5e6f7a8b9c0d1
+          description: The resource ID.
+        - name: key
+          in: path
+          required: true
+          schema:
+            type: string
+            examples:
+              - sequence_number
+          description: The state key name.
+      responses:
+        '200':
+          description: The stored value (a JSON object or array).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/State'
+              examples:
+                object:
+                  summary: Object value
+                  value:
+                    cursor: '2025-08-10T14:22:33.000Z'
+                    pageToken: abc123
+                array:
+                  summary: Array value
+                  value:
+                    - id: 1001
+                      status: synced
+                    - id: 1002
+                      status: pending
+        '400':
+          description: The resource ID is not a valid identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The resource type does not support state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: State not available for the given model.
+        '404':
+          description: The resource or key was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - message: State not found for key.
+    put:
+      x-internal: false
+      operationId: setResourceStateValue
+      tags:
+        - State
+      summary: Create or update a resource-scoped state value
+      description: |-
+        Sets the value for a state key under a specific resource. Creates
+        the key if it does not exist; replaces the value if it does.
+
+        The request body must be a non-empty JSON object or array. Bare
+        JSON primitives (strings, numbers, booleans, `null`) and empty
+        containers (`{}`, `[]`) are rejected.
+
+        Only `exports`, `imports`, and `integrations` support
+        resource-scoped state.
+
+        This is an upsert — check the status code to distinguish create (201)
+        from update (200). The response body is plain text, not JSON.
+      parameters:
+        - name: resourceType
+          in: path
+          required: true
+          schema:
+            type: string
+            enum:
+              - exports
+              - imports
+              - integrations
+            x-enumDescriptions:
+              exports: State scoped to a specific export
+              imports: State scoped to a specific import
+              integrations: State scoped to a specific integration
+          description: |-
+            The resource type. Only `exports`, `imports`, and
+            `integrations` are supported.
+        - name: _resourceId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 66a1f2c3b4d5e6f7a8b9c0d1
+          description: The resource ID.
+        - name: key
+          in: path
+          required: true
+          schema:
+            type: string
+            examples:
+              - sequence_number
+          description: The state key name.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              description: |-
+                A non-empty JSON object or array to store. Bare primitives
+                and empty containers are not accepted.
+              $ref: '#/components/schemas/State'
+            examples:
+              object:
+                summary: Store an object
+                value:
+                  cursor: '2025-08-10T14:22:33.000Z'
+                  pageToken: abc123
+              array:
+                summary: Store an array
+                value:
+                  - id: 1001
+                    status: synced
+                  - id: 1002
+                    status: pending
+      responses:
+        '200':
+          description: Existing key updated.
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - OK
+                x-enumDescriptions:
+                  OK: The existing key was updated successfully.
+        '201':
+          description: New key created.
+          content:
+            text/plain:
+              schema:
+                type: string
+                enum:
+                  - Created
+                x-enumDescriptions:
+                  Created: A new key was created successfully.
+        '400':
+          description: |-
+            Invalid request. The body is not valid JSON, is a bare
+            primitive, or the resource ID is invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_json:
+                  summary: Body is not valid JSON (bare primitive)
+                  value:
+                    errors:
+                      - message: Unexpected token '"', ""just a string"" is not valid JSON
+                invalid_id:
+                  summary: Resource ID is not a valid identifier
+                  value:
+                    errors:
+                      - code: invalid_ref
+                        message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The resource type does not support state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: State not available for the given model.
+        '404':
+          description: The resource was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: Export not found.
+        '415':
+          description: |-
+            The `Content-Type` header is missing or is not
+            `application/json`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - message: Content-Type should equal application/json
+        '422':
+          description: |-
+            The request body is empty, or is an empty container (`{}` or
+            `[]`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: missing_request_body
+                    message: Please send state as request body in the PUT request.
+    delete:
+      x-internal: false
+      operationId: deleteResourceStateKey
+      tags:
+        - State
+      summary: Delete a resource-scoped state key
+      description: |-
+        Deletes a specific state key and its value from the resource.
+        Returns `404` if the key does not exist.
+      parameters:
+        - name: resourceType
+          in: path
+          required: true
+          schema:
+            type: string
+            enum:
+              - exports
+              - imports
+              - integrations
+            x-enumDescriptions:
+              exports: State scoped to a specific export
+              imports: State scoped to a specific import
+              integrations: State scoped to a specific integration
+          description: |-
+            The resource type. Only `exports`, `imports`, and
+            `integrations` are supported.
+        - name: _resourceId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 66a1f2c3b4d5e6f7a8b9c0d1
+          description: The resource ID.
+        - name: key
+          in: path
+          required: true
+          schema:
+            type: string
+            examples:
+              - sequence_number
+          description: The state key name.
+      responses:
+        '204':
+          description: Key deleted.
+        '400':
+          description: The resource ID is not a valid identifier.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: Please provide a valid _id.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          description: The resource type does not support state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - code: invalid_ref
+                    message: State not available for the given model.
+        '404':
+          description: The resource or key was not found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                errors:
+                  - message: State not found for key.
+components:
+  schemas:
+    State:
+      description: |-
+        A stored state value. Values must be non-empty JSON objects or arrays —
+        bare primitives, `null`, and empty containers (`{}`, `[]`) are rejected.
+        Keys are upserted: PUT creates the key if absent and replaces the value
+        if present.
+      oneOf:
+        - title: object
+          type: object
+          minProperties: 1
+        - title: array
+          type: array
+          minItems: 1
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+x-enable-proxy: true
+x-internal: false