@celigo/api-specs 0.2.1

package/dist/tag.yml

@@ -0,0 +1,553 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Tags
+  description: API for managing the account-level tag catalog — short-code labels applied to flow-step errors for triage.
+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: Tags
+    description: |-
+      API for managing the account-level tag catalog. Tags are short-code labels
+      that can be applied to flow-step errors for classification and triage.
+
+      ## Tag schema
+
+      {% openapi-schemas spec="tag" schemas="Tag" grouped="true" %}
+paths:
+  /v1/tags:
+    get:
+      x-internal: false
+      operationId: listTags
+      tags:
+        - Tags
+      parameters:
+        - name: limit
+          in: query
+          description: Maximum number of records to return per page.
+          schema:
+            type: integer
+            minimum: 1
+            examples:
+              - 100
+        - $ref: '#/components/parameters/After'
+      summary: List the account's tag catalog
+      description: |-
+        Returns every tag defined in the account, each with its short `tagId`
+        code and human-readable `tag` name. This is the catalog that backs the
+        tag-picker on flow-step errors (`PUT /v1/flows/{_id}/{_stepId}/tags`).
+
+        The `tagId` field is the short code used as a write-side input on
+        flow-step tag mutations (`PUT /v1/flows/{_id}/{_stepId}/tags`
+        accepts `tagIds: ["NjMMA", ...]`), while the human name is stored
+        on the error record as `tags: ["Ignore", ...]`.
+      responses:
+        '200':
+          description: Array of tag entries (at least one tag exists).
+          headers:
+            Link:
+              description: |-
+                RFC-5988 pagination links. When more pages remain, includes a `<...>; rel="next"` entry;
+                absent on the final page.
+              schema:
+                type: string
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Tag'
+              examples:
+                default:
+                  value:
+                    - _id: 6555119c0a137977fb1e7994
+                      tag: Ignore
+                      tagId: NjMMA
+                    - _id: 69a1e79bdbb446adf7933049
+                      tag: IT Related Login Issue
+                      tagId: P3mzf
+        '204':
+          description: No tags exist in the account.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    post:
+      x-internal: false
+      operationId: createTag
+      tags:
+        - Tags
+      summary: Create a tag
+      description: |-
+        Creates a new tag in the account's tag catalog. The server generates
+        an immutable short `tagId` code automatically. Tag names are
+        case-insensitively unique within the account — a case-variant
+        duplicate is rejected with HTTP 422 `[create_not_allowed]` "A tag
+        with this name already exists." Per Celigo's documentation, the
+        catalog holds at most 1,000 unique tags per account. Note the
+        per-error limit is separate and much smaller: a single error carries
+        at most 3 tags (see `PUT /v1/flows/{_id}/{_stepId}/tags`).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              default:
+                value:
+                  tag: Urgent
+      responses:
+        '201':
+          description: The created tag entry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Tag'
+              examples:
+                default:
+                  value:
+                    _id: 65d6cd9e83ba5b97e2658fce
+                    tag: Urgent
+                    tagId: rx618
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/tags/{_id}:
+    get:
+      x-internal: false
+      operationId: getTagById
+      tags:
+        - Tags
+      summary: Get a tag
+      description: Returns a single tag entry by its `_id`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 65d6cd9e83ba5b97e2658fce
+          description: The tag ID.
+      responses:
+        '200':
+          description: The tag entry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Tag'
+              examples:
+                default:
+                  value:
+                    _id: 65d6cd9e83ba5b97e2658fce
+                    tag: Urgent
+                    tagId: rx618
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      operationId: updateTag
+      tags:
+        - Tags
+      summary: Update a tag
+      description: |-
+        Updates the human-readable `tag` name for an existing tag entry.
+        The short `tagId` code is immutable and cannot be changed.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 65d6cd9e83ba5b97e2658fce
+          description: The tag ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              default:
+                summary: Rename a tag
+                value:
+                  tag: Production Issue
+      responses:
+        '200':
+          description: The updated tag entry.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Tag'
+              examples:
+                default:
+                  value:
+                    _id: 65d6cd9e83ba5b97e2658fce
+                    tag: Production Issue
+                    tagId: rx618
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    patch:
+      x-internal: false
+      operationId: patchTag
+      tags:
+        - Tags
+      summary: Patch a tag
+      description: |-
+        Partially updates a tag using a JSON Patch document (RFC 6902).
+        Only the `replace` operation is supported, and only on the following
+        whitelisted path:
+
+        | Path | Description |
+        |------|-------------|
+        | `/tag` | The human-readable tag name |
+
+        All other paths are rejected with `422`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 65d6cd9e83ba5b97e2658fce
+          description: The tag ID.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/JsonPatchRequest'
+            examples:
+              rename_tag:
+                summary: Rename a tag
+                value:
+                  - op: replace
+                    path: /tag
+                    value: Production
+      responses:
+        '204':
+          description: Tag patched successfully.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      operationId: deleteTag
+      tags:
+        - Tags
+      summary: Delete a tag
+      description: Permanently deletes a tag from the account's tag catalog.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: objectId
+            examples:
+              - 65d6cd9e83ba5b97e2658fce
+          description: The tag ID.
+      responses:
+        '204':
+          description: Tag deleted successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  parameters:
+    After:
+      name: after
+      in: query
+      required: false
+      description: |-
+        Opaque cursor for forward pagination. Pass the value from the `Link`
+        response header (`rel="next"`) to fetch the next page.
+      schema:
+        type: string
+  schemas:
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    Tag:
+      type: object
+      required:
+        - _id
+        - tag
+        - tagId
+      description: |-
+        One tag entry from the account's tag catalog. `tag` is the human
+        display name; `tagId` is the 5-char short code used when writing tag
+        references on flow-step errors.
+      allOf:
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            tag:
+              type: string
+              maxLength: 100
+              examples:
+                - Urgent
+              description: Human-readable tag name. Appears on read-side error records.
+            tagId:
+              type: string
+              readOnly: true
+              minLength: 5
+              maxLength: 5
+              pattern: ^[a-zA-Z0-9]{5}$
+              examples:
+                - rx618
+              description: |-
+                Short code used when writing tag references — e.g. as the values
+                in `PUT /v1/flows/{_id}/{_stepId}/tags` `tagIds[]`.
+                Server-generated and immutable: `tagId` values supplied on
+                create/update are ignored and a fresh code is generated.
+    Request:
+      type: object
+      description: Fields for creating or updating a tag.
+      required:
+        - tag
+      properties:
+        tag:
+          type: string
+          minLength: 1
+          maxLength: 100
+          examples:
+            - Urgent
+          description: |-
+            The human-readable tag name. Case-insensitively unique within the
+            account. Whitespace is trimmed on save; names that are empty after
+            trimming are rejected.
+    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
+    JsonPatchOperation:
+      type: object
+      description: A single JSON Patch operation (RFC 6902).
+      required:
+        - op
+        - path
+      properties:
+        op:
+          type: string
+          enum:
+            - replace
+            - add
+            - remove
+          x-enumDescriptions:
+            replace: Replaces the value at the specified path.
+            add: Sets the value at the specified path.
+            remove: Removes the value at the specified path.
+          description: The operation to perform.
+        path:
+          type: string
+          description: |-
+            JSON Pointer (RFC 6901) to the field to patch. Only
+            whitelisted paths are accepted — unlisted paths return
+            `422` with `"<path> is not a whitelisted property"`.
+        value:
+          description: The new value to set. Required for `replace` and `add`, omit for `remove`.
+    JsonPatchRequest:
+      type: array
+      description: |-
+        A JSON Patch document (RFC 6902). Send an array of patch
+        operations on whitelisted fields — all other paths are rejected
+        with 422.
+      minItems: 1
+      items:
+        $ref: '#/components/schemas/JsonPatchOperation'
+  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
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+x-enable-proxy: true
+x-internal: false