← Knowledge base
Developer documentation · REST API v1

Conversation API

Read your support data from your own integration. Retrieve conversations and their history with standard authenticated JSON requests.

Getting started

A read-only API

The API covers email and widget conversations, customer details, assignment, tags, message bodies, and files stored in OutcomeArc. Private notes and unsent drafts require an explicit key permission. It does not send replies, modify data, or run a migration into another platform for you.

Base URLhttps://app.outcomearc.com/api/v1

Use HTTPS from a trusted server. All endpoints use GET and return application/json. IDs are UUID strings; timestamps are ISO-8601 values with a timezone. Missing optional values are null. Clients should tolerate new response fields within v1.

Authentication

  1. As a workspace owner or administrator, open Settings → API.
  2. Name the key and select the inboxes it may read. Optionally enable Include private notes, unsent drafts, and their attachments; this is off by default.
  3. Create the key and copy it once. Keep it in your server’s secret storage, for example as OUTCOMEARC_API_KEY.
Authorization: Bearer <YOUR_API_KEY>

Keys start with oa_api_, expire after 90 days, and can be revoked in Settings. Only a hash is stored. To rotate a key or change access, create a replacement and revoke the old key. Up to 50 active keys are allowed per workspace.

Access is checked on every request against the key’s selected inboxes and its creator’s current administrator role and inbox permissions. New inboxes are not automatically included. Deleted inboxes are excluded. A missing or inaccessible resource returns the same 404.

Keep credentials out of client-side code. Never put a key in a URL, browser bundle, ticket, or log. This API does not enable cross-origin browser access. Supabase session tokens, webhook secrets, and MCP tokens are not API keys.

First request

curl --fail-with-body 'https://app.outcomearc.com/api/v1/inboxes' \
  --header "Authorization: Bearer $OUTCOMEARC_API_KEY"

Pagination & filters

Conversation, message, and attachment lists return data, pagination, and private_content_included. Lists are ordered oldest first by created_at, then ID. The private-content flag describes the key’s permission, not whether a particular page contains notes or drafts.

limit
Optional integer, 1–50. Default: 25.
cursor
Omit on the first request. For the next page, pass the previous response’s pagination.next_cursor unchanged. Stop when it is null.

Keep the same endpoint and filters between pages. You may reduce limit to handle large responses. Cursors are opaque continuation positions, not credentials; every page is authorized again. There is no offset ceiling, total count, or bulk-export job.

Conversation filters

These parameters apply only to GET /conversations and are combined with AND:

inbox_id
Required. One inbox ID returned by /inboxes.
status
all (default), open, pending, closed, or spam. All includes spam; the three individual status filters exclude spam. The app’s Active status is open here.
created_after
Inclusive creation timestamp, for example 2026-01-01T00:00:00Z.
created_before
Exclusive creation timestamp. Must be later than created_after when both are supplied.
updated_after
Inclusive conversation-update timestamp. This is not a change feed for every customer, tag, or message edit.

URL-encode values, including + in timezone offsets. Unknown or duplicate query parameters are rejected. Lists are live, not point-in-time snapshots: concurrent imports, moves, edits, or deletions can change what is returned. Deduplicate by stable ID and reconcile after activity has stopped when completeness is required.

Inboxes

GET/inboxes

Returns all currently accessible inboxes selected for this key, at most 50. This endpoint takes no query parameters and is not paginated. Each item has id, name, and email (nullable).

{
  "data": [
    {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Support",
      "email": "support@example.com"
    }
  ]
}

Conversations

GET/conversations

Lists conversations in one granted inbox, including closed, spam, and AI-only widget conversations by default. Conversation records do not embed messages or attachment lists.

curl --fail-with-body --get 'https://app.outcomearc.com/api/v1/conversations' \
  --header "Authorization: Bearer $OUTCOMEARC_API_KEY" \
  --data-urlencode 'inbox_id=22222222-2222-4222-8222-222222222222' \
  --data-urlencode 'status=all' \
  --data-urlencode 'limit=25'
{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "inbox_id": "22222222-2222-4222-8222-222222222222",
      "subject": "Question about my account",
      "status": "closed",
      "is_spam": false,
      "channel": "email",
      "conversation_type": "human",
      "priority": "normal",
      "created_at": "2026-01-01T10:00:00+00:00",
      "updated_at": "2026-01-02T11:00:00+00:00",
      "last_message_at": "2026-01-02T11:00:00+00:00",
      "closed_at": "2026-01-02T11:00:00+00:00",
      "snoozed_until": null,
      "external_source": null,
      "external_id": null,
      "customer": {
        "id": "33333333-3333-4333-8333-333333333333",
        "name": "Alex",
        "email": "alex@example.com",
        "external_id": null,
        "timezone": "UTC",
        "custom_data": {
          "plan": "trial"
        },
        "created_at": "2026-01-01T10:00:00+00:00",
        "updated_at": "2026-01-01T10:00:00+00:00"
      },
      "assignee": null,
      "team": null,
      "tags": [
        {
          "id": "44444444-4444-4444-8444-444444444444",
          "name": "Account",
          "color": "#64748b"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 25,
    "next_cursor": null
  },
  "private_content_included": false
}
GET/conversations/{conversation_id}

Returns one conversation as { "data": { …conversation fields… } }, without pagination. Takes no query parameters.

Conversation fields

  • id, inbox_id, subject, status, is_spam, and priority describe the current conversation. Spam is a boolean, not a stored status.
  • channel is email or widget. conversation_type distinguishes human and ai conversations.
  • created_at, updated_at, and last_message_at are timestamps. closed_at and snoozed_until are nullable.
  • external_source and external_id retain an imported conversation’s source identity when available. They are not OutcomeArc IDs.
  • customer includes ID, name, email, external ID, timezone, custom data, and creation/update timestamps. Private customer-profile notes are excluded. Widget identities may use a synthetic email address.
  • assignee is null or an object with id, name, and email. team is null or an object with id and name.
  • tags is an array of id, name, and color objects; an untagged conversation returns [].

Messages

GET/conversations/{conversation_id}/messages

Returns chronological message history. Supports limit and cursor. Page through this endpoint independently for each conversation.

{
  "data": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "conversation_id": "11111111-1111-4111-8111-111111111111",
      "kind": "email",
      "direction": "inbound",
      "body_text": "Can you help with my account?",
      "body_html": "<p>Can you help with my account?</p>",
      "delivery_status": "delivered",
      "email_message_id": null,
      "in_reply_to": null,
      "created_at": "2026-01-01T10:00:00+00:00",
      "updated_at": "2026-01-01T10:00:00+00:00",
      "sent_at": null,
      "author": {
        "id": "33333333-3333-4333-8333-333333333333",
        "name": "Alex",
        "email": "alex@example.com",
        "external_id": null
      },
      "recipients": {
        "to": [
          "support@example.com"
        ],
        "cc": [],
        "bcc": []
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "next_cursor": null
  },
  "private_content_included": false
}
  • kind distinguishes email, chat, note, and draft records. direction is inbound, outbound, or internal. Notes, drafts, and internal messages are omitted unless private-content access was granted.
  • body_text and nullable body_html contain the stored bodies without API truncation. An empty body means no content was retained in that format; the API does not invent missing text. Treat HTML as untrusted and sanitize it before rendering.
  • author contains nullable id, name, email, and external_id. Stored source authors are retained when available; missing details remain null.
  • recipients contains to, cc, and bcc as retained by the source. Older records may have no recipients; imported values may be strings or address objects rather than a uniform address format.
  • delivery_status is the stored delivery state. Do not interpret a draft as sent. sent_at, email_message_id, and in_reply_to are nullable; creation and update timestamps are always included.

Raw provider payloads, internal metadata, original headers, widget session credentials, and audit events are not returned. Private-content permission cannot be enabled through a query parameter.

Attachments

GET/conversations/{conversation_id}/attachments

Lists attachment metadata with limit and cursor. Match message_id to the message list. Only files attached to visible, persisted messages are included; unattached upload staging is never exposed.

{
  "data": [
    {
      "id": "66666666-6666-4666-8666-666666666666",
      "conversation_id": "11111111-1111-4111-8111-111111111111",
      "message_id": "55555555-5555-4555-8555-555555555555",
      "file_name": "receipt.pdf",
      "content_type": "application/pdf",
      "byte_size": 10420,
      "content_id": null,
      "created_at": "2026-01-01T10:00:00+00:00"
    }
  ],
  "pagination": {
    "limit": 25,
    "next_cursor": null
  },
  "private_content_included": false
}

byte_size is the stored size in bytes. content_id is nullable and identifies a CID inline image where retained. A source attachment that was never downloaded into OutcomeArc storage is not available through this endpoint.

GET/attachments/{attachment_id}/download

Rechecks key, inbox, and private-content access, then returns a private download link. Takes no query parameters. The API returns JSON, not a redirect or file bytes.

{
  "data": {
    "url": "https://storage.example.com/short-lived-signed-url",
    "expires_in": 60
  }
}

Fetch the returned URL within 60 seconds without forwarding your API Authorization header to the storage host. Treat the URL as a secret. Request a fresh link if it expires. Already-issued links may remain usable for up to 60 seconds after key revocation. Deleted or unavailable files may fail when fetched.

Limits & errors

The workspace shares a limit of 120 requests per 60-second window across all its API keys. On 429, wait at least the Retry-After value (60 seconds) before retrying. Use bounded concurrency and backoff for temporary failures.

Responses are capped at 4 MiB. An oversized response returns 413, not truncated content. Retry with a smaller page, down to limit=1. If a single record still exceeds the cap, this API cannot return that record; do not treat the export as complete.

StatusCodeMeaning
400invalid_request / invalid_cursorInvalid ID, filter, date, page size, or cursor. Correct the request before retrying.
401unauthorizedMissing, invalid, expired, or revoked key; also applies if its creator no longer has an administrator role.
404not_found / attachment_unavailableMissing or inaccessible resource, unsupported route, or unavailable stored file.
405method_not_allowedOnly GET is supported.
413response_too_largeResponse exceeds 4 MiB. Reduce page size.
429rate_limitedWorkspace budget exhausted. Respect Retry-After.
503temporarily_unavailableTemporary service or query failure. Retry later; narrow the date range or page size for expensive queries.
{
  "error": {
    "code": "not_found",
    "message": "Resource not found or not accessible to this key.",
    "request_id": "request-identifier"
  }
}

API responses use Cache-Control: no-store. Error responses include a request ID for support; normal handler responses also include X-Request-Id. Infrastructure-level errors may use a different format. Never send credentials or customer message bodies with a diagnostic report.

Using the data in another platform

Discover inboxes, page through conversations, and retrieve each conversation’s message and attachment pages. Your integration is responsible for mapping these records to the destination platform’s import API, preserving private-note and draft visibility, and handling destination-specific limits and permissions.

Use OutcomeArc IDs as source identifiers to avoid duplicate imports. Do not send imported drafts or replay historical replies as new outbound email. This API provides ordinary resource reads, not a destination-specific connector, full workspace backup, or guaranteed point-in-time export.

Only retained data is available. Permanently erased conversations, unlinked customers, skipped source attachments, and history never stored in OutcomeArc cannot be reconstructed. For a complete migration, reconcile source and destination records and resolve every failed page or file download before considering the work finished.