API reference (v1)

Authenticate every /v1 request with Authorization: Bearer <api key>. Errors are application/problem+json with a stable code: INVALID_INPUT (400), PERMISSION_DENIED/ACTION_DISABLED (403), NOT_FOUND (404), CONNECTION_NEEDS_REAUTH (409), RATE_LIMITED/QUOTA_EXCEEDED (429), PROVIDER_ERROR (502), TIMEOUT (504). Responses carry X-Request-Id. Per-key rate limit: 600 requests/minute (SETU_RATE_PER_MINUTE); monthly call quota per project: SETU_MONTHLY_CALL_LIMIT.

Method & path	Purpose
`GET /v1/toolkits`, `GET /v1/toolkits/{slug}`	Catalog; `configured` is false when the instance has no OAuth app for it
`GET /v1/tools?toolkits=a,b&format=raw\|openai\|anthropic`	Tool definitions
`GET /v1/tools/search?q=&toolkits=&limit=&format=`	Ranked tool search
`POST /v1/connections/initiate` `{user_id, toolkit, redirect_url?, scopes?}`	Returns `connect_url` for the end user. `redirect_url` must be on the project's allow-list
`POST /v1/connections/api-key` `{user_id, toolkit, api_key}`	For API-key toolkits
`GET /v1/connections?user_id=&toolkit=`, `GET/DELETE /v1/connections/{id}`	Status; delete revokes and erases secrets
`POST /v1/execute` `{user_id, action, input, connection_id?, account?, confirm?}`	Run `toolkit.action`. If the user has several accounts for the app, pass `account` (its label) or `connection_id`. Destructive actions need `confirm: true`
`POST /v1/sessions` `{user_id, toolkits?, actions?, mode?, ttl_seconds?}`	Scoped session; returns `mcp_url`
`ANY /v1/mcp/{session_id}`	MCP streamable HTTP endpoint (the session id is the credential)
`GET /oauth/callback/{toolkit}`	Provider redirect target (not called by you)
`GET /healthz`, `GET /readyz`	Liveness, readiness

user_id is any stable string that identifies your end user. Connections are scoped to (project, user_id).

Examples#

All examples assume export SETU_BASE_URL=https://api.setuagent.com and export SETU_API_KEY=....

Start a connection#

Shell

curl -X POST $SETU_BASE_URL/v1/connections/initiate \
  -H "authorization: Bearer $SETU_API_KEY" -H "content-type: application/json" \
  -d '{"user_id":"user_1","toolkit":"github"}'

JSON

{ "connection_id": "con_...", "connect_url": "https://github.com/login/oauth/authorize?...", "status": "initiated" }

Show connect_url to your user. Poll GET /v1/connections/{connection_id} until status is active.

Run an action#

Shell

curl -X POST $SETU_BASE_URL/v1/execute \
  -H "authorization: Bearer $SETU_API_KEY" -H "content-type: application/json" \
  -d '{"user_id":"user_1","action":"github.create_issue",
       "input":{"owner":"acme","repo":"app","title":"Login button is misaligned"}}'

JSON

{ "data": { "number": 42, "url": "https://github.com/acme/app/issues/42" }, "http_status": 201 }

Search tools#

Shell

curl "$SETU_BASE_URL/v1/tools/search?q=post+a+message&toolkits=slack&limit=3&format=openai" \
  -H "authorization: Bearer $SETU_API_KEY"

Returns { "tools": [...] } in the requested format. See Errors for the error shape.