Custom source

Use a custom source when your customer data lives in a system we don’t connect to: an in-house CRM, support desk or call system. Your server pushes records to OpenScaffold over HTTPS. You don’t open a firewall port, you don’t give us your credentials, and you choose exactly what leaves your network. Everything you push is read like any other source: versioned, quoted word for word, and attributed to the person who wrote it.

Connect

Create the token

A workspace admin opens Settings › Sources › Custom source and connects it. The token (os_push_…) is shown once. Store it as a secret, for example OPENSCAFFOLD_PUSH_TOKEN, never in code or logs.

Hand the setup prompt to your coding agent

The same screen shows a prompt with the full contract and your token. Paste it into Claude Code, Cursor or Codex on the repository that holds your customer data. The agent maps your data to the fields below, shows you the mapping, writes the sync job and runs the checks in Verify before backfilling.

Backfill and schedule

Push your history once, then run the job on a schedule (every 15 minutes works) or on your own change events.

Push records

curl -X POST https://app.openscaffold.ai/api/sources/push \
  -H "Authorization: Bearer $OPENSCAFFOLD_PUSH_TOKEN" \
  -H "Content-Type: application/json" \
  -d @records.json

The body holds 1 to 100 records:

records.json

{
  "records": [
    {
      "id": "case-17",
      "container": { "id": "acct-acme", "name": "Acme" },
      "title": "SSO rollout",
      "url": "https://crm.example.com/cases/17",
      "occurredAt": "2026-11-01T09:00:00Z",
      "updatedAt": "2026-11-02T09:00:00Z",
      "customerDomains": ["acme.com"],
      "messages": [
        {
          "id": "m1",
          "author": { "name": "Dana Ruiz", "email": "dana@acme.com" },
          "text": "We need SCIM before go-live.",
          "at": "2026-11-01T09:00:00Z"
        },
        {
          "id": "m2",
          "author": { "name": "Sam Lee", "email": "sam@yourcompany.com" },
          "text": "Escalated to engineering.",
          "at": "2026-11-02T09:00:00Z",
          "internal": true
        }
      ]
    }
  ]
}

Record fields

string

required

Your stable id for the record (1–200 characters). The same id is the same record; never reuse an id for a different record.

object

required

The collection the record belongs to, as { "id", "name" }. Use one container per customer account. Each container appears under Sources and can be switched off there.

string

required

When the record started. ISO 8601 with Z or an offset.

string

Your record’s last-modified time. Always send it. A newer updatedAt makes a new version; an older one is ignored as stale. Without it, the newest message time decides.

array

required

Every message, note or comment in the record, oldest first (up to 2,000).

string[]

The customer’s email domains (up to 20), when you know them. They decide which customer the record belongs to.

string

Optional, up to 500 characters.

string

Optional link back to the record in your system. https only. OpenScaffold never fetches it.

boolean

true, with a newer updatedAt, when the record was deleted on your side. A record with no text is treated the same way.

Message fields

string

required

Your stable message id. It lets OpenScaffold re-read only what changed when a record is edited.

object

required

{ "name", "email" }, with email when you know it. Your own team should use your company email so OpenScaffold knows they are on your side.

string

required

The exact words, up to 40,000 characters.

string

required

When it was written. ISO 8601 with Z or an offset.

boolean

true for notes your team wrote that the customer never saw. They are never read as the customer’s words.

Leave out fields you don’t have (null also works). Unknown fields are refused. No timestamp may be more than 5 minutes in the future.

Responses

Status	Body	What to do
`200`	`{ "stored", "unchanged", "stale", "switchedOff" }`	Done. `switchedOff` lists containers someone switched off; records sent there are dropped.
`400`	`{ "error" }`	The whole batch was refused. The error names the bad field. Fix it and resend.
`401`	`{ "error" }`	The token is wrong or the source was disconnected. Stop and check with your admin.
`429`	`{ "error" }`, `Retry-After` header	Over the hourly limit. Wait for `Retry-After`, then resend.
`503`	`{ "error" }`	Nothing was stored. Retry with backoff.

Resending is always safe. The same record twice counts as unchanged; a changed record with a newer updatedAt becomes a new version, and what OpenScaffold knows about the customer is updated from it.

Limits


Records per request	100
Request size	under 4 MB
Messages per record	2,000
Characters per record	400,000
Characters per message	40,000
New record versions per hour	5,000 (unchanged resends don’t count)
Containers per source	500

Push batches one request at a time.

Verify

Before you backfill, check the job with three real records:

Push them. The response says "stored": 3.
Push the same three again. It says "unchanged": 3.
Change one message’s text and send that record with a newer updatedAt. It says "stored": 1.
Open Settings › Sources › Custom source and check the records are there.

Who sees it, and what you answer for

OpenScaffold trusts the authors your server sends, the same way it trusts who Slack or Linear says wrote a message. A message from dana@acme.com counts as the customer’s own words. Only send authors your own system knows.

Everyone in the workspace sees it. Every container your server sends is switched on when it first arrives and shared with the whole workspace.
Switching a container off drops what is sent to it from then on. To stop the source completely, disconnect it.
Disconnecting refuses the token at once. To use a new token, disconnect and connect again.
The token acts for the admin who created it. It stops working if they are no longer a workspace admin.
Every quote from a custom source cites its record, so you can always see where it came from.
Keep the token out of logs. Log counts and record ids, never record text.

Get started

For coding agents

Reference

Connect

Push records

Record fields

Message fields

Responses

Limits

Verify

Who sees it, and what you answer for