Chats · Oblive Docs

List chats

GET/organizations/{organizationId}/chats

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

Query Parameters

cursor?string

Opaque cursor returned by the previous page.

limit?integer

sortBy?string

Value in

"id"
"title"
"status"
"lastMessageAt"
"createdAt"
"updatedAt"

sortDirection?string

Value in

"asc"
"desc"

status?string

Value in

"open"
"archived"

isOnboardingChat?boolean

q?string

Case-insensitive search across chat titles and visible message content.

Response Body

`application/json`

curl -X GET "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats"

{  "success": true,  "statusCode": 200,  "message": "Chats listed.",  "data": [    {      "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",      "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",      "title": "Customer Escalation",      "status": "open",      "summary": null,      "harnessSessionId": null,      "settings": {        "pinnedTaskIds": []      },      "lastMessageAt": "2026-01-01T00:00:00.000Z",      "archivedAt": null,      "createdAt": "2026-01-01T00:00:00.000Z",      "updatedAt": "2026-01-01T00:00:00.000Z",      "isOnboardingChat": false    }  ],  "pagination": {    "cursor": null,    "limit": 50,    "nextCursor": null,    "previousCursor": null,    "hasNextPage": false,    "hasPreviousPage": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Create chat

POST/organizations/{organizationId}/chats

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats" \  -H "Content-Type: application/json" \  -d '{    "title": "Customer Escalation"  }'

{  "success": true,  "statusCode": 201,  "message": "Chat created.",  "data": {    "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "title": "Customer Escalation",    "status": "open",    "summary": null,    "harnessSessionId": null,    "settings": {      "pinnedTaskIds": []    },    "lastMessageAt": "2026-01-01T00:00:00.000Z",    "archivedAt": null,    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z",    "isOnboardingChat": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Get chat

GET/organizations/{organizationId}/chats/{id}

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

id*string

Resource identifier.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "success": true,  "statusCode": 200,  "message": "Chat found.",  "data": {    "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "title": "Customer Escalation",    "status": "open",    "summary": null,    "harnessSessionId": null,    "settings": {      "pinnedTaskIds": []    },    "lastMessageAt": "2026-01-01T00:00:00.000Z",    "archivedAt": null,    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z",    "isOnboardingChat": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 404,  "message": "Chat not found.",  "error": {    "code": "chat_not_found"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Update chat

PATCH/organizations/{organizationId}/chats/{id}

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

id*string

Resource identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X PATCH "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "title": "Customer Escalation"  }'

{  "success": true,  "statusCode": 200,  "message": "Chat updated.",  "data": {    "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "title": "Customer Escalation",    "status": "open",    "summary": null,    "harnessSessionId": null,    "settings": {      "pinnedTaskIds": []    },    "lastMessageAt": "2026-01-01T00:00:00.000Z",    "archivedAt": null,    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z",    "isOnboardingChat": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 404,  "message": "Chat not found.",  "error": {    "code": "chat_not_found"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 409,  "message": "Wait for the active assistant response to finish before archiving this chat.",  "error": {    "code": "chat_response_active"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Delete chat

DELETE/organizations/{organizationId}/chats/{id}

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

id*string

Resource identifier.

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "success": true,  "statusCode": 200,  "message": "Chat deleted.",  "data": {    "id": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "title": "Customer Escalation",    "status": "open",    "summary": null,    "harnessSessionId": null,    "settings": {      "pinnedTaskIds": []    },    "lastMessageAt": "2026-01-01T00:00:00.000Z",    "archivedAt": null,    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z",    "isOnboardingChat": false  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 404,  "message": "Chat not found.",  "error": {    "code": "chat_not_found"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 409,  "message": "The organization onboarding chat cannot be changed.",  "error": {    "code": "onboarding_chat_immutable"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Stream chat events

GET/organizations/{organizationId}/chats/{chatId}/events

Starts with the latest persisted assistant snapshot, then streams revisioned message updates.

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

Header Parameters

Last-Event-ID?string

Last processed event in assistantMessageId:revision format.

Response Body

`text/event-stream`

curl -X GET "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/events" \  -H "Last-Event-ID: d4ad2b33-d18c-45c2-965d-22a883af9d89:4"

"id: d4ad2b33-d18c-45c2-965d-22a883af9d89:4\nevent: chat.snapshot\ndata: {\"type\":\"chat.snapshot\"}\n\n"

Cancel assistant response

POST/organizations/{organizationId}/chats/{chatId}/messages/{messageId}/cancel

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

messageId*string

Assistant message identifier.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/messages/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel"

{  "success": true,  "statusCode": 200,  "message": "Message cancellation requested.",  "data": {    "id": "380c8d1f-7a6a-4a8d-8dd9-3e9ecda3f4f1",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "replyToMessageId": null,    "role": "assistant",    "status": "cancelling",    "revision": 1,    "author": {      "kind": "human",      "displayName": "Operator"    },    "parts": [      {        "id": "part-1",        "kind": "text",        "text": "Create the onboarding plan."      }    ],    "error": null,    "completedAt": "2026-01-01T00:00:00.000Z",    "createdAt": "2026-01-01T00:00:00.000Z",    "updatedAt": "2026-01-01T00:00:00.000Z"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 404,  "message": "Assistant message not found.",  "error": {    "code": "message_not_found"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 409,  "message": "Assistant message cannot be cancelled from its current state.",  "error": {    "code": "message_not_cancellable"  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

Upload a chat attachment

PUT/organizations/{organizationId}/chats/{chatId}/attachments/{attachmentId}

Stores up to 50 MB of supported reference content under a client-generated, chat-scoped identifier.

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

attachmentId*string

Client-generated attachment identifier.

Formatuuid

Query Parameters

fileName*string

mediaType*string

Request Body

application/octet-stream

TypeScript Definitions

Use the request body type in TypeScript.

body*file

Formatbinary

Response Body

`application/json`

curl -X PUT "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/attachments/497f6eca-6276-4993-bfeb-53cbbbba6f08?fileName=string&mediaType=string" \  -H "Content-Type: application/octet-stream" \  -d 'string'

{  "success": true,  "statusCode": 201,  "message": "Chat attachment stored.",  "data": {    "version": 1,    "id": "31d22752-e70d-42ce-a28a-39dc87dc8fc8",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "chatId": "0ce65ee0-dcd9-46c2-90a4-243f5d54dc66",    "fileName": "project-brief.md",    "mediaType": "text/markdown",    "sizeBytes": 2048,    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",    "createdAt": "2026-07-15T09:00:00.000Z",    "uri": "oblive://organizations/7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1/chats/0ce65ee0-dcd9-46c2-90a4-243f5d54dc66/attachments/31d22752-e70d-42ce-a28a-39dc87dc8fc8"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed",    "issues": [      {        "path": "organizationId",        "message": "Must be a valid UUID.",        "code": "invalid_format"      }    ]  },  "meta": {    "timestamp": "2026-01-01T00:00:00.000Z"  }}

{  "success": false,  "statusCode": 409,  "message": "Attachments can only be added to open, non-onboarding chats.",  "error": {    "code": "attachment_not_allowed"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

{  "success": false,  "statusCode": 413,  "message": "Attachments cannot exceed 50 MB.",  "error": {    "code": "attachment_invalid"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

{  "success": false,  "statusCode": 415,  "message": "Attachment type is unsupported.",  "error": {    "code": "attachment_invalid"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

Read chat attachment bytes

GET/organizations/{organizationId}/chats/{chatId}/attachments/{attachmentId}/content

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

attachmentId*string

Client-generated attachment identifier.

Formatuuid

Query Parameters

disposition?string

Value in

"inline"
"attachment"

Header Parameters

Range?string

Response Body

`application/octet-stream`

`application/json`

curl -X GET "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/attachments/497f6eca-6276-4993-bfeb-53cbbbba6f08/content"

"string"

"string"

{  "success": false,  "statusCode": 404,  "message": "Chat attachment not found.",  "error": {    "code": "attachment_not_found"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

{  "success": false,  "statusCode": 416,  "message": "Requested byte range is not satisfiable.",  "error": {    "code": "range_not_satisfiable"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

Read chat attachment metadata

HEAD/organizations/{organizationId}/chats/{chatId}/attachments/{attachmentId}/content

Path Parameters

organizationId*string

Organization identifier.

Formatuuid

chatId*string

Chat identifier.

Formatuuid

attachmentId*string

Client-generated attachment identifier.

Formatuuid

Query Parameters

disposition?string

Value in

"inline"
"attachment"

Header Parameters

Range?string

Response Body

`application/octet-stream`

`application/json`

curl -X HEAD "https://example.com/organizations/497f6eca-6276-4993-bfeb-53cbbbba6f08/chats/497f6eca-6276-4993-bfeb-53cbbbba6f08/attachments/497f6eca-6276-4993-bfeb-53cbbbba6f08/content"

"string"

"string"

{  "success": false,  "statusCode": 404,  "message": "Chat attachment not found.",  "error": {    "code": "attachment_not_found"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

{  "success": false,  "statusCode": 416,  "message": "Requested byte range is not satisfiable.",  "error": {    "code": "range_not_satisfiable"  },  "meta": {    "timestamp": "2026-07-15T09:00:00.000Z"  }}

200application/json

400application/json

201application/json

400application/json

200application/json

400application/json

404application/json

200application/json

400application/json

404application/json

409application/json

200application/json

400application/json

404application/json

409application/json

200text/event-stream

200application/json

404application/json

409application/json

201application/json

400application/json

409application/json

413application/json

415application/json

200application/octet-stream

206application/octet-stream

404application/json

416application/json

200application/octet-stream

206application/octet-stream

404application/json

416application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`text/event-stream`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/octet-stream`

`application/octet-stream`

`application/json`

`application/json`

`application/octet-stream`

`application/octet-stream`

`application/json`

`application/json`