Create sources with the Dialogues API

Create sources with the Dialogues API

Use a Dialogues Developer API key (dak_*) and Cursor skills to create sources from sample JSON or CSV — without using the App Sheaf connector wizard.

Sources are one facet of a Connector (see Register a Connector): the data contract describing schema, parser, and delivery — how bytes arrive (owner_upload file uploads, client_push streams from your software, owner_ui in-app entry, local_sync device sync). Publishing a source automatically declares it on your connector, satisfying the register-first/validate-at-ingest rule.

Get a developer key

1. Sign in at App Sheaf (topos.dialogues.ai or your Sheaf host)
2. Open Profile → API keys (/profile/api-keys)
3. Create a key and copy DIALOGUES_API_KEY=dak_... (shown once)

Or issue via API with your Sheaf session access token (Supabase JWT from browser devtools):

curl -sS -X POST "$CONTROL_PLANE_URL/v1/dialogues/api-keys" \
  -H "Authorization: Bearer $SHEAF_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"CLI"}'

Cursor skills

Install skills from the Topos repo (.cursor/skills/):

• dialogues:create-connector — the full decision tree: infer schema from sample data, build source_definition_json with delivery, configure the client facet, submit or export
• dialogues:create-source / dialogues:add-auth — deprecated pointers to dialogues:create-connector

Infer schema from sample data

export CONTROL_PLANE_URL=https://cp.logu3s.com
export DIALOGUES_API_KEY=dak_...

curl -sS -X POST "$CONTROL_PLANE_URL/v1/dialogues/sources/infer-schema" \
  -H "Authorization: Bearer $DIALOGUES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "sample.csv",
    "content": "id,content\n1,hello\n",
    "format": "auto"
  }'

Publish a source

curl -sS -X POST "$CONTROL_PLANE_URL/v1/dialogues/sources" \
  -H "Authorization: Bearer $DIALOGUES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_definition_json": { "source_id": "...", "source_type": "file", ... },
    "delivery": "owner_upload",
    "visibility": "private"
  }'

• private — appears in your owned sources catalog
• public — also listed in the public source directory
• delivery — optional; derived from source_type when omitted (file → owner_upload, stream → client_push). The response echoes the resolved value and the declaration lands on your connector.

Set "install": true with topos_key, user_id, topos_id, and dataset_id to install on your engine in the same request.

Paste install (no API submit)

Export source_definition_json from the skill, then in Topos:

1. Sources → Advanced install
2. Choose sourcedefinitionjson
3. Paste JSON and click Install

Register the client facet

Software that pushes data (or reads) needs the connector's client facet — auth mode, profile, redirects:

curl -sS -X POST "$CONTROL_PLANE_URL/v1/dialogues/apps" \
  -H "Authorization: Bearer $DIALOGUES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "app_id": "my-app",
    "allowed_source_ids": ["browser_visits"],
    "allowed_scopes": ["activity:write"],
    "client_auth_mode": "public_pkce",
    "integration_profile": "web",
    "allowed_redirect_uris": ["https://example.com/callback"]
  }'

(/v1/connectors accepts the same payload with a sources declarations list; allowed_source_ids stays in sync either way.)

Then follow Add Dialogues auth to implement Grant Access.

Keys

Do not use TOPOS_KEY for registry mutations. (TOPOS_KEY rows were historically called "connectors" — they are engine device keys, unrelated to the Connector registry.)