Tale Notifications API

openapi: 3.2.0
info:
  title: Tale Dev Notifications API
  version: 3.27.0
  contact:
    name: Tale
    url: https://tale.dev
  description: 'Operations tagged Notifications across 2 of this provider''s published API definitions: tale-dev-openapi-original.json, tale-dev-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{origin}'
  description: The deployment this document describes — `GET /openapi.json` on a running instance fills it in
  variables:
    origin:
      default: https://your-host.example.com
      description: Scheme and host of the Tale deployment
security:
- bearerAuth: []
tags:
- name: Notifications
  description: Read-only, recipient-scoped notification exports for connected applications.
paths:
  /api/v1/notifications/sync:
    get:
      tags:
      - Notifications
      operationId: listNotificationsForSync
      summary: Read a member’s notifications for one-way mirroring
      security:
      - bearerAuth: []
      description: Organization owners and administrators may export the personal and organization streams of an active, verified member identified by email — and so may any other member an administrator delegated the export to by granting the `tale:notifications.export` capability in the organization’s competence register (organization-scoped, optionally expiring, revocable, and revoked when the membership ends); `GET /api/v1/me` answers `capabilities.notificationExport`. Security visibility follows the recipient’s role. Missing, disabled, unverified or ambiguous recipients return an empty completed page. Walk both streams completely before retracting missing destination rows; failed scans must preserve the previous mirror. This endpoint never marks Tale notifications read. Source ids are stable and org-prefixed; version changes with content or read state. Paths use the same destinations as the Tale bell, relative to the configured browser origin (which may require ZeroTier), never the machine transport URL. Text uses the requested locale or the organization default, with English fallback; titles and bodies are bounded to 500 and 8000 characters.
      parameters:
      - name: X-Organization-Slug
        in: header
        required: false
        schema:
          type: string
        description: The organization to operate on. STRICTLY REQUIRED on every call, reads included, when the key holder belongs to more than one organization — without it such requests are refused with 400 `ORG_SLUG_REQUIRED` (the dashboard’s last-active organization never steers a machine call). A slug that names no organization answers 404 `ORG_SLUG_INVALID`, one the key holder is no member of 403 `ORG_FORBIDDEN`. Single-organization keys may omit it; a blank or whitespace-only value reads as the header absent. Each of the three refusals lists the slugs the key holder may send under `data.organizations`; `GET /api/v1/me` answers them too.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: The previous page’s `continueCursor`, unchanged — opaque; omit for the first page. A value this list did not answer is refused with 400 `INVALID_CURSOR` rather than read as the first page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: Page size, 1..100 (default 100; out-of-range numbers are clamped, a value that is not a number answers 400 `INVALID_LIMIT`)
      - name: recipientEmail
        in: query
        required: true
        schema:
          type: string
          format: email
          maxLength: 320
        description: Verified email of the intended recipient
      - name: stream
        in: query
        required: true
        schema:
          type: string
          enum:
          - personal
          - organization
        description: Walk each stream independently with its own cursor
      - name: locale
        in: query
        required: false
        schema:
          type: string
          enum:
          - en
          - de
          - fr
        description: Defaults to the organization’s language
      - name: X-Request-Id
        in: header
        required: false
        description: 'Your own correlation id, echoed back on the response and written to the platform’s log: up to 255 characters of letters, digits, `_`, `-` and `=`. Any other value is replaced by a fresh UUID (the response carries the id that was used), and uniqueness of an id you choose is yours to keep.'
        schema:
          type: string
          pattern: ^[A-Za-z0-9_=-]{1,255}$
      responses:
        '200':
          description: One page of the recipient’s stream
          content:
            application/json:
              schema:
                type: object
                x-tale-pagination: keyset
                required:
                - recipientId
                - page
                - isDone
                - continueCursor
                properties:
                  recipientId:
                    type:
                    - string
                    - 'null'
                  isDone:
                    type: boolean
                  continueCursor:
                    type: string
                  page:
                    type: array
                    maxItems: 100
                    items:
                      type: object
                      required:
                      - id
                      - version
                      - title
                      - body
                      - path
                      - createdAt
                      - read
                      properties:
                        id:
                          type: string
                        version:
                          type: string
                          pattern: ^[a-f0-9]{64}$
                        title:
                          type: string
                          maxLength: 500
                        body:
                          type: string
                          maxLength: 8000
                        path:
                          type: string
                          description: Organization-scoped /dashboard/ path with encoded entity ids and query parameters
                        createdAt:
                          type: integer
                          minimum: 0
                        read:
                          type: boolean
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '304':
          description: Not Modified — `If-None-Match` named the current `ETag`, so the body is not sent
          headers:
            ETag:
              $ref: '#/components/headers/ETag'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '400':
          description: 'Invalid request: a body the schema refuses — a wrong type, an unknown key, a missing field, a NUL or an unpaired surrogate, a whole number beyond 2^53 − 1 (`INVALID_BODY`, every problem under `data.issues`); a query parameter the operation does not take, given twice or left blank (`INVALID_QUERY`); on a list, a `limit` that is not a whole number (`INVALID_LIMIT`) or a `cursor` this list did not answer (`INVALID_CURSOR`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '401':
          description: Missing or invalid API key (`UNAUTHORIZED`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            WWW-Authenticate:
              $ref: '#/components/headers/WWWAuthenticate'
        '403':
          description: The key holder is neither an organization owner or administrator nor holds a live `tale:notifications.export` capability grant (`ROLE_FORBIDDEN`); or `X-Organization-Slug` names an organization the key holder is no member of (`ORG_FORBIDDEN`, with the slugs the key holder may send under `data.organizations`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '404':
          description: '`X-Organization-Slug` names no organization (`ORG_SLUG_INVALID`, with the slugs the key holder may send under `data.organizations`)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '405':
          description: The path exists, but not for this method (`METHOD_NOT_ALLOWED`); `Allow` names the methods it serves
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Allow:
              $ref: '#/components/headers/Allow'
        '429':
          description: 'The key holder’s request budget is spent (`RATE_LIMITED`): `Retry-After` names the wait in whole seconds and `data.retryAfterMs` in milliseconds; the envelope carries a `requestId`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
        '500':
          description: Internal error (`INTERNAL_ERROR`); the envelope carries a `requestId` to quote when reporting it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
        '503':
          description: 'The platform’s database is restarting or cannot be reached (`DATABASE_UNAVAILABLE`): `Retry-After` names the wait in whole seconds — retry with backoff; the envelope carries a `requestId`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-Tale-Api-Version:
              $ref: '#/components/headers/XTaleApiVersion'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
    servers:
    - url: '{origin}'
      description: The deployment this document describes — `GET /openapi.json` on a running instance fills it in
      variables:
        origin:
          default: https://your-host.example.com
          description: Scheme and host of the Tale deployment
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - code
      properties:
        error:
          type: string
          description: What went wrong
        code:
          type: string
          enum:
          - ACTOR_AMBIGUOUS
          - ACTOR_DISABLED
          - ACTOR_FORBIDDEN
          - ACTOR_NOT_FOUND
          - ACTOR_REBOUND
          - ACTOR_UNVERIFIED
          - API_KEY_SCOPE_FORBIDDEN
          - ATTACHMENT_NOT_FOUND
          - ATTACHMENT_NOT_OWNED
          - ATTACHMENT_NOT_STAGED
          - ATTACHMENT_SIZE_MISMATCH
          - AUTHOR_UNVERIFIED
          - AUTOMATION_DELIVERY_SCOPE_MISMATCH
          - AUTOMATION_HAS_ACTIVE_RUNS
          - AUTOMATION_INPUT_INVALID
          - AUTOMATION_NOT_DEPLOYED
          - AUTOMATION_NOT_FOUND
          - AUTOMATION_NOT_INSTALLED
          - AUTOMATION_PROJECT_FORBIDDEN
          - AUTOMATION_PROJECT_SCOPE_REQUIRED
          - AUTOMATION_TRIGGER_INVALID
          - AUTOMATION_VERSION_NOT_DEPLOYED
          - AUTOMATION_VERSION_UNKNOWN
          - BLOB_NOT_FOUND
          - BODY_CHUNK_MALFORMED
          - BODY_LENGTH_MISMATCH
          - BODY_TOO_LARGE
          - BROWSER_SESSION_NOT_FOUND
          - BUDGET_EXCEEDED
          - CHAT_MODEL_AMBIGUOUS
          - CHAT_MODEL_NOT_ON_PROVIDER
          - CHAT_MODEL_UNKNOWN
          - CHAT_PROVIDER_UNKNOWN
          - CHAT_THREAD_ARCHIVED
          - CHAT_THREAD_NOT_DIRECT
          - CHAT_TURN_IN_PROGRESS
          - CHAT_TURN_NOT_RUNNING
          - CONTACT_AMBIGUOUS
          - CONTACT_DUPLICATE_EMAIL
          - CONTACT_DUPLICATE_EXTERNAL_ID
          - CONTACT_IDENTITY_REQUIRED
          - CONTACT_NOT_FOUND
          - CONTACT_STALE
          - CONVERSATION_CLOSED
          - CONVERSATION_CONTACT_CONFLICT
          - CONVERSATION_CONTACT_TRASHED
          - CONVERSATION_NOT_FOUND
          - CONVERSATION_SNAPSHOT_CONFLICT
          - CONVERSATION_SOURCE_NOT_FOUND
          - DATABASE_UNAVAILABLE
          - DELIVERY_NOT_FOUND
          - DELIVERY_RECEIPT_CONFLICT
          - DELIVERY_RETRY_UNAVAILABLE
          - DELIVERY_UNACKNOWLEDGED
          - DOCUMENT_HAS_KNOWLEDGE_ENTRY
          - DOCUMENT_NOT_FOUND
          - DOCUMENT_RECORD_FROZEN
          - DOCUMENT_RECORD_PROTECTED
          - DOCUMENT_RECORD_REPLACEMENT_REQUIRED
          - DOCUMENT_STALE
          - DUPLICATE_PRODUCT_EXTERNAL_ID
          - DUPLICATE_PRODUCT_NAME
          - EMBEDDING_CREDENTIAL_REJECTED
          - EMBEDDING_CREDIT_EXHAUSTED
          - EMBEDDING_NOT_CONFIGURED
          - EMBEDDING_UPSTREAM_ERROR
          - EMPTY_ANSWER
          - FILE_NOT_FOUND
          - FILE_SIZE_INVALID
          - FILE_TOO_LARGE
          - FOLDER_DEPTH_EXCEEDED
          - FOLDER_NAME_INVALID
          - FOLDER_NAME_TAKEN
          - FOLDER_NOT_ACCESSIBLE
          - FOLDER_NOT_FOUND
          - FORBIDDEN_DEPLOYMENT_EDITOR
          - FORBIDDEN_INSTANCE_ADMIN
          - HTTP_ERROR
          - HUMAN_ASK_EXPIRED
          - HUMAN_ASK_NOT_FOUND
          - HUMAN_ASK_NOT_PENDING
          - IDEMPOTENCY_KEY_REUSED
          - INTEGRATION_NOT_OWNED
          - INTERNAL_ERROR
          - INVALID_BODY
          - INVALID_CURSOR
          - INVALID_HEADER
          - INVALID_LIMIT
          - INVALID_QUERY
          - INVALID_SESSION
          - INVALID_SKILL
          - INVALID_SKILL_SLUG
          - INVALID_URL
          - KNOWLEDGE_ENTRY_DUPLICATE
          - KNOWLEDGE_ENTRY_FORBIDDEN
          - KNOWLEDGE_ENTRY_NOT_FOUND
          - KNOWLEDGE_ENTRY_STORE_TIMEOUT
          - KNOWLEDGE_ENTRY_SUPERSEDED
          - LEGAL_HOLD_ACTIVE
          - MENTION_DIRECTORY_UNAVAILABLE
          - MESSAGE_NOT_FOUND
          - METHOD_NOT_ALLOWED
          - MODEL_API_CONCURRENCY_EXCEEDED
          - MODEL_API_DISABLED
          - MODEL_API_FORBIDDEN
          - MODEL_API_GUARDRAIL_BLOCKED
          - MODEL_API_GUARDRAIL_UNAVAILABLE
          - MODEL_API_GUARDRAIL_UNSUPPORTED
          - MODEL_API_MODEL_FORBIDDEN
          - MODEL_API_MODEL_UNKNOWN
          - MODEL_API_TEXT_TOO_LARGE
          - MODEL_API_TOOLS_UNSUPPORTED
          - MODEL_API_UNAVAILABLE
          - MODEL_API_UPSTREAM_ERROR
          - MODEL_API_VENDOR_TOOL_UNSUPPORTED
          - MODEL_API_VISION_UNSUPPORTED
          - NOT_FOUND
          - OBJECT_STORE_UNAVAILABLE
          - OBJECT_STORE_UNCONFIGURED
          - ORG_FORBIDDEN
          - ORG_SLUG_INVALID
          - ORG_SLUG_REQUIRED
          - ORIGIN_FORBIDDEN
          - PRECONDITION_FAILED
          - PRODUCT_NOT_FOUND
          - PRODUCT_STALE
          - PROJECT_AGENT_CONNECTOR_UNKNOWN
          - PROJECT_AGENT_HARNESS_INVALID
          - PROJECT_AGENT_LIMIT
          - PROJECT_AGENT_MANAGED
          - PROJECT_AGENT_MODEL_INVALID
          - PROJECT_AGENT_NAME_TAKEN
          - PROJECT_AGENT_NOT_FOUND
          - PROJECT_AGENT_PROVIDER_UNKNOWN
          - PROJECT_AGENT_SECRETS_FORBIDDEN
          - PROJECT_AGENT_SECRET_UNKNOWN
          - PROJECT_AGENT_SKILL_UNKNOWN
          - PROJECT_AGENT_STALE
          - PROJECT_AGENT_TOOL_UNKNOWN
          - PROJECT_ARCHIVED
          - PROJECT_DUPLICATE_EXTERNAL_ID
          - PROJECT_FORBIDDEN
          - PROJECT_HAS_BOUND_AUTOMATIONS
          - PROJECT_HAS_PROTECTED_RECORDS
          - PROJECT_KEY_INVALID
          - PROJECT_KEY_TAKEN
          - PROJECT_LEGAL_HOLD
          - PROJECT_NOT_FOUND
          - PROJECT_SHARING_INVALID
          - PURGE_INCOMPLETE
          - RATE_LIMITED
          - RBAC_FORBIDDEN
          - REQUEST_TIMEOUT
          - REVIEW_COMPETENCE_REQUIRED
          - REVIEW_INDEPENDENT_REVIEWER_REQUIRED
          - ROLE_FORBIDDEN
          - RUN_ACTIVE
          - RUN_NOT_FOUND
          - RUN_QUARANTINED
          - RUN_QUARANTINE_CHANGED
          - SETUP_FOLDER_MISSING
          - SKILL_EXISTS
          - SKILL_FILE_NOT_FOUND
          - SKILL_FORBIDDEN
          - SKILL_MALFORMED
          - SKILL_NOT_FOUND
          - SKILL_PUBLISH_FORBIDDEN
          - SKILL_STALE
          - SKILL_TEAM_UNKNOWN
          - STANDARD_AGENT_OFF
          - STANDARD_AGENT_UNAVAILABLE
          - TASK_AGENT_REVIEW_REQUIRED
          - TASK_ARCHIVED
          - TASK_AUTOMATION_DISABLED
          - TASK_AUTOMATION_UNAVAILABLE
          - TASK_EXTERNAL_REF_INVALID
          - TASK_EXTERNAL_STATUS_STALE
          - TASK_HAS_LIVE_RUN
          - TASK_HAS_OPEN_SUBTASKS
          - TASK_LABEL_UNKNOWN
          - TASK_NOT_FOUND
          - TASK_NOT_IN_REVIEW
          - TASK_REVIEW_POLICY_UNAVAILABLE
          - TASK_STATUS_CONFLICT
          - TEAM_ACCESS_DENIED
          - TEAM_INHERITED_FROM_FOLDER
          - TEAM_NOT_IN_ORG
          - THREAD_NOT_FOUND
          - UNAUTHORIZED
          - UNSUPPORTED_FILE_TYPE
          - UPLOAD_FILE_MISMATCH
          - UPLOAD_INTENT_INVALID
          - UPLOAD_POLICY_REJECTED
          - UPSTREAM_UNAVAILABLE
          - URI_TOO_LONG
          - WEBSITE_DOMAIN_IMMUTABLE
          - WEBSITE_DOMAIN_INVALID
          - WEBSITE_DOMAIN_NOT_CRAWLABLE
          - WEBSITE_DUPLICATE_DOMAIN
          - WEBSITE_INVALID_LIST_URL
          - WEBSITE_NOT_FOUND
          description: 'A stable refusal code — every refusal the door itself makes carries one, and so does every domain refusal it lets through. The set is additive: a new code is a minor change, so treat a value you do not know as a generic refusal of the status you got.'
        requestId:
          type: string
          description: The response’s `X-Request-Id`, repeated on a 429, on a 500, on a body-size 413 and on a URL-size 414 so a caller can quote it
        data:
          type: object
          properties:
            retryAfterMs:
              type: number
              description: Wait in milliseconds for RATE_LIMITED
            providers:
              type: array
              items:
                type: string
              description: For CHAT_MODEL_AMBIGUOUS, the provider slugs that serve the model — name one as `providerSlug`
            lastMessageId:
              type: string
              description: 'For CHAT_TURN_NOT_RUNNING, the newest assistant message on the thread (once it has one) — the idle poll’s own disambiguation: equal to the `messageId` a 202 named means that turn already settled'
            lastStatus:
              type: string
              enum:
              - pending
              - complete
              - failed
              - cancelled
              description: For CHAT_TURN_NOT_RUNNING, how `lastMessageId` settled (present with it)
            organizations:
              type: array
              description: For ORG_SLUG_REQUIRED, ORG_SLUG_INVALID and ORG_FORBIDDEN, the organizations the key holder belongs to (a disabled membership is left out; the list is empty when none remains) — send one of the slugs as `X-Organization-Slug`
              items:
                type: object
                required:
                - slug
                - name
                properties:
                  slug:
                    type: string
                  name:
                    type: string
            issues:
              type: array
              description: For INVALID_BODY and INVALID_QUERY, every problem the schema found in the body or the query string; for INVALID_LIMIT and INVALID_CURSOR, the one parameter refused (`limit`, `cursor`); for AUTOMATION_INPUT_INVALID, every problem the automation’s inputs schema found in the run input (at most 20 either way), each naming the field and the reason; `error` repeats the first one
              items:
                type: object
                required:
                - path
                - message
                properties:
                  path:
                    type: string
                    description: The field, dotted for nesting (`address.city`, `contacts.2.email`); empty for a problem with the body as a whole
                  message:
                    type: string
            scope:
              type: string
              enum:
              - user
              - team
              - project
              - org
              - apiKey
              description: 'For BUDGET_EXCEEDED, whose cap is reached: the key holder’s own (`user`), one of their teams’ (`team`), that of the project the work belongs to (`project`), the organization’s (`org`) or this API key’s (`apiKey`)'
            period:
              type: string
              enum:
              - daily
              - weekly
              - monthly
              description: For BUDGET_EXCEEDED, what the cap counts over — a calendar day, ISO week or calendar month in UTC
            limitCode:
              type: string
              enum:
              - TOKEN_LIMIT
              - COST_LIMIT
              - REQUEST_LIMIT
              description: 'For BUDGET_EXCEEDED, which cap is reached: tokens, cost in cents, or requests'
            used:
              type: number
              description: For BUDGET_EXCEEDED, the usage the cap measured this period, in its unit (tokens, cents or requests)
            limit:
              type: number
              description: For BUDGET_EXCEEDED, the cap, in the same unit
            resetsAt:
              type: number
              description: For BUDGET_EXCEEDED, when the period resets, in epoch milliseconds — `Retry-After` names the same wait in whole seconds
  headers:
    Allow:
      description: The methods this path serves, comma-separated
      schema:
        type: string
        example: GET, POST, HEAD, OPTIONS
    ETag:
      description: 'A validator: over the answer’s bytes on a JSON read, the stored object’s tag on a download. Send it back as `If-None-Match` — as received; the weak and edge-suffixed forms match too — to be told 304 when nothing changed.'
      schema:
        type: string
    XTaleApiVersion:
      description: The version of this contract (`info.version`) the serving instance implements — semver for the wire
      schema:
        type: string
        example: 3.27.0
    WWWAuthenticate:
      description: 'The challenge RFC 9110 §11.6.1 requires of a 401: `Bearer`, or `Bearer error="invalid_token"` when a key was presented and refused'
      schema:
        type: string
    RetryAfter:
      description: How long to wait before retrying, in whole seconds
      schema:
        type: integer
        minimum: 1
    CacheControl:
      description: '`private, no-cache` on a validated read and on a download: keep the answer, revalidate it before reuse, and let no shared cache keep it. Every other answer says `no-store`.'
      schema:
        type: string
    XRequestId:
      description: The request id the platform logged this call under — quote it when reporting a problem. Echoes a sane `X-Request-Id` the caller sent.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An organization API key. Create one in Settings → API. Pasted into the explorer on /docs it stays in the page’s memory only and is forgotten on reload — it is never stored.
x-refined-from:
- tale-dev-openapi-original.json
- tale-dev-openapi.yml