Five-minute agent connection

1. Create the agent

Sign in, select the Account, open Access, and choose Create agent. Name the integration and select the exact Sources it needs. Restrict datasets and limits when the integration needs less than the whole Source. New Sources remain unchecked and are never inherited by an ordinary grant.

If WorkOS Agent Registration is enabled, complete that registration. Otherwise, copy the one-time-visible WorkOS organization API key. Combined stores only its WorkOS credential reference and obfuscated display value.

Set the returned secret and Account UUID in your runtime environment:

export COMBINED_API_URL=https://platform.trycombined.com
export COMBINED_TOKEN='one-time-visible-agent-credential'
export COMBINED_ACCOUNT_ID='00000000-0000-4000-8000-000000000000'

Never commit the token. If it is exposed, revoke the agent and create a replacement.

2. Inspect the catalogue

curl --fail-with-body \
  -H "Authorization: Bearer $COMBINED_TOKEN" \
  "$COMBINED_API_URL/v1/catalog?accountId=$COMBINED_ACCOUNT_ID"

The response contains only granted Sources, datasets, and fields. Use each Source's logicalName with the dataset schema and table to form a three-part SQL relation.

3. Query

curl --fail-with-body \
  -H "Authorization: Bearer $COMBINED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "00000000-0000-4000-8000-000000000000",
    "sql": "select application, count(*) as events from desktop_capture_ab12cd34.context.application_activity group by 1 order by 2 desc limit 20",
    "parameters": [],
    "maxRows": 1000
  }' \
  "$COMBINED_API_URL/v1/sql"

Only one read-only SELECT or CTE-to-SELECT is accepted. File paths, URLs, system catalogues, extension management, table functions, DDL, and DML are rejected.

4. Record the receipt

The response includes receiptId, exact row/truncation information, duration, a bounded scan estimate, and the Account grant version. Bounded results may remain in the isolated result cache for five minutes; receipts never retain result content.

5. Revoke

Delete the agent's Source grant from Access. Revocation increments the Account grant version. A query that started under an earlier version is discarded before its result can be returned.

Next steps

• Use authentication to choose human OAuth or agent credentials.
• Use catalogue and SQL concepts before constructing dynamic queries.
• Use TypeScript, Python, or MCP for a production integration.
• Read API errors before implementing retry behavior.