Chat attachments

Methods, permissions, request fields and response schemas for chat attachments.

Read and search

Retrieve current records, history and status.

Read attachment limits and typesSupported attachment capabilities. Documents are limited to 5 MiB and always downloaded as attachments.GET/chat/attachments/capabilities

Token scope chat:readActor permission memberAction type read

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Supported attachment capabilities. Documents are limited to 5 MiB and always downloaded as attachments.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/chat/attachments/capabilities" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "documents": {
          "type": "boolean"
        },
        "maxFileBytes": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "documents",
        "maxFileBytes"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Download an accessible chat documentDownload a document after conversation and uploader access checks.GET/chat/attachments/:conversationId/:uploaderId/:fileId

Token scope chat:readActor permission memberAction type read

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.
`uploaderId`Required	string · uuid	Resource UUID scoped to the current organization.
`fileId`Required	string · uuid	Resource UUID scoped to the current organization.

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Binary application/octet-stream response with Content-Disposition: attachment and private/no-store headers; ordinary API redaction does not touch bytes.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X GET "$BASE/chat/attachments/$CONVERSATION_ID/$UPLOADER_ID/$FILE_ID" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN"

Success response schema · HTTP 200

{
  "application/octet-stream": {
    "schema": {
      "type": "string",
      "format": "binary"
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.

Create and import

Add records, prepare imports or start a new setup.

Upload a conversation documentStore a validated document so you can attach it to a conversation message.POST/chat/attachments/:conversationId

Token scope chat:writeActor permission memberAction type write

Send Idempotency-Key. Retry the same intended action with the same key and exact payload to retrieve its saved result.

Path parameters

Field	Type	Description and constraints
`conversationId`Required	string · uuid	Resource UUID scoped to the current organization.

Request body

Field	Type	Description and constraints
`name`Required	string	At least 1 characters · At most 200 characters
`mimeType`Required	string	One of: "application/pdf", "text/plain", "text/csv", "text/markdown", "application/msword", "application/vnd.ms-excel", "application/vnd.ms-powerpoint", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.openxmlformats-officedocument.presentationml.presentation", "application/zip"
`base64`Required	string	At least 4 characters · At most 6990508 characters

Explore this request

Edit example fields and validate the request against its schema.

What you receive

Stored attachment metadata with an authenticated document URL; byte signature, extension and MIME must agree.

Request example · cURL

Replace example IDs and values. Supply the token from your secret store. Each intended write uses one stable $ACTION_KEY.

curl -X POST "$BASE/chat/attachments/$CONVERSATION_ID" \
  -H "Authorization: Bearer $ALLPROFILES_API_TOKEN" \
  -H "Idempotency-Key: $ACTION_KEY" \
  -H "Content-Type: application/json" \
  --data '{"name":"example.txt","mimeType":"text/plain","base64":"UGxlYXNlIHJldmlldyB0aGUgcmVudGFsIGRldGFpbHMuCg=="}'

Full JSON request schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "mimeType": {
      "type": "string",
      "enum": [
        "application/pdf",
        "text/plain",
        "text/csv",
        "text/markdown",
        "application/msword",
        "application/vnd.ms-excel",
        "application/vnd.ms-powerpoint",
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
        "application/zip"
      ]
    },
    "base64": {
      "type": "string",
      "minLength": 4,
      "maxLength": 6990508
    }
  },
  "required": [
    "name",
    "mimeType",
    "base64"
  ],
  "additionalProperties": false
}

Success response schema · HTTP 201

{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "minLength": 0,
          "maxLength": 2048
        },
        "name": {
          "type": "string",
          "minLength": 0,
          "maxLength": 200
        },
        "mimeType": {
          "type": "string",
          "minLength": 0,
          "maxLength": 128
        },
        "size": {
          "type": "integer",
          "minimum": 1,
          "maximum": 5242880
        }
      },
      "required": [
        "url",
        "name",
        "mimeType",
        "size"
      ],
      "additionalProperties": true
    }
  }
}

Errors and recovery

400: Invalid JSON, request fields, query, path identifier or missing Idempotency-Key.
401: Missing, invalid, revoked or expired organization API token; its issuing actor must still be the current organization owner.
403: Token scope or actor capability denied, disabled/banned account, or action unavailable.
404: Unknown route or resource not accessible in the bound organization. Cross-tenant resources are not enumerated.
409: Conflicting profile/rental state, duplicate resource, idempotency payload mismatch or operation still in progress.
410: event_cursor_expired: the event cursor is behind retained history. Reconcile current resources and start from the supplied recovery cursor.
422: Business validation/moderation rejected the operation. CHAT_MESSAGE_BLOCKED was not delivered.
429: API rate/concurrency limit exceeded; use backoff and Retry-After when present.
500: Internal operation error. Sensitive implementation details are not returned. Investigate using the request ID before repeating a write.
503: Provider or configuration unavailable; uncertain writes must retain the same Idempotency-Key.

These are documented API errors. The local sandbox checks schema fields only and does not test authorization, moderation or provider behavior.

Financial fields named ...Cents or ...InCents use integer cents. Path fields and nested constraints are shown above and in the downloadable OpenAPI contract.