- Base URL:
https://conigma-tool-server-production.up.railway.app - Sign-in: a workspace API key, sent as
Authorization: Bearer sk_…. Your Personal key works as is. - Reference: every endpoint and field is in the Tool API reference.
Use this API from a server. Never put an API key in a browser app or a mobile app: anyone who reads the key can spend the workspace’s credits.
How it works
1
Find the tool
GET /api/tools?query=instagram profile returns matching tools, best first. Searching is free.2
Read its inputs and price
GET /api/tool/{toolId} returns the inputSchema (JSON Schema), whether your key can run it (availability), whether it needs a connected account (connection) and what it costs (pricing). This is free and runs nothing.3
Run it
POST /api/tool/{toolId} with {"input": {…}} and an Idempotency-Key header. Successful calls that end within 25 seconds answer 200 with the result. Failures return the error codes below. Longer calls answer 202 and keep running.4
Get the outcome of a long call
Poll
GET /api/tool-invocations/{invocationId} every few seconds (it answers 202 until the call ends), or pass a webhook URL when you run the tool and Connie POSTs the outcome to it. See Webhooks.Quickstart
- curl
- Node.js
- Python
Retry safely with idempotency keys
Every run needs anIdempotency-Key header: 8 to 200 characters (letters, digits and . _ : ~ + / = -), one per logical operation. A UUID you generate and store with your job works well.
- Same key, same request: Connie returns the original operation, marked
"replayed": true, and runs and charges nothing again ("chargedThisRequest": 0). Use this when a response was lost or timed out. If nothing ran anderror.retryableistrue, the same key lets Connie try the operation again. - Same key, different input or webhook:
409 idempotency_conflict. Nothing runs. - New key: a new run, charged again.
- Keys and outcomes are kept for 24 hours. After that, the same key answers
409 replay_expiredand never runs again.
Outcomes
Running or polling a tool returns an operation: the outcome, or an error with the same shape. Search, tool details and webhook-secret endpoints return their own response shapes. On search, authentication errors can instead use{"error":"message","code":"api_key_required"}; check the HTTP status before reading the body.
billing.chargedCredits is what the call cost; billing.items has a line per tool it ran. The price from GET /api/tool/{toolId} is an estimate: the receipt is the charge.
Connie keeps running a call through its own server restarts. A call already running when Connie deploys finishes on the old server. Calls Connie knows only read from the web or a data provider (scrapes, dataset collections, searches, lookups) and are interrupted by a crash run once more automatically, and are charged once. A call that writes or sends, or one Connie can’t confirm only reads, is never run twice: if its outcome is lost it reads
unknown_outcome.Errors you can retry
For anot_executed response with error.retryable: true, wait for the Retry-After header, then send the same request with the same Idempotency-Key. Examples include:
Do not retry based only on HTTP
503 or the presence of Retry-After. feature_unavailable means new tool operations are disabled for the workspace; invalid_schema means the tool’s editor must fix its schema. Both have error.retryable: false. Contact support for feature_unavailable, or the tool’s editor for invalid_schema, before trying again.
The full list of codes and limits is in Errors and limits.
Limits
Over a limit you get
429 with Retry-After, and nothing runs. See Plans.
Good to know
- Permissions: a key acts as one workspace member and can run what that member can, with their connected accounts. Tools that need a connected account say so in
connection; connect the account in Connie first. See API keys. - Tool ids are case-sensitive. URL-encode them once:
/becomes%2F. - Credits: API runs show in the credit usage log as coming from an API key. See Credits.
- Browsers: the API answers cross-origin requests, but don’t call it from a browser with a real key. Run it from your server.