Documentation
DashAPI Connect
One HTTP API for company data, web research, social, SEO and media. You send an execution, Connect picks the provider, falls back on failure and returns a result with the price already fixed.
- Plain HTTPS and JSON. No SDK required.
- Every operation has a typed input schema and a fixed price per call.
- Server-side only. Keys never go in browsers, mobile apps or URLs.
- Machine keys run reads only. Writes and spend actions need a human approval.
Quickstart
You need a key and a funded balance. Create both in Konnect.
1. Export your key
export CONNECT_KEY=dck_... # create one in Konnect, shown once2. List what you can call
curl https://api.dashapi.ai/external/v1/capabilities \
-H "Authorization: Bearer $CONNECT_KEY"3. Submit an execution
curl -X POST https://api.dashapi.ai/external/v1/executions \
-H "Authorization: Bearer $CONNECT_KEY" \
-H "Content-Type: application/json" \
-d '{
"capability": "web.search",
"version": 1,
"credential": { "mode": "managed" },
"input": { "q": "northwind.io funding" },
"idempotency_key": "order-77",
"budget": { "max_micro_usd": 10000 }
}'HTTP/1.1 202 Accepted
Location: /external/v1/executions/exe_01JC...
{ "id": "exe_01JC...", "status": "accepted" }4. Read the result
curl https://api.dashapi.ai/external/v1/executions/exe_01JC... \
-H "Authorization: Bearer $CONNECT_KEY"Acceptance is not completion. Poll until status is terminal, and do not infer success from the 202.
Authentication
Send your key as a bearer token. Nothing else is accepted.
dck_<24 hex key id>.<43 base64url secret>- Header only:
Authorization: Bearer dck_.... Any query string is rejected. - HTTPS only. Plain requests fail with
400 tls_requiredbefore the key is read. - No CORS. Browser calls will fail, by design.
- We store a SHA-256 digest and an 8 character prefix. The secret is shown once and cannot be recovered.
- A bad key, an expired key, a revoked key and a disabled client all return the same
401.
Your client owns execution history and grants, not the key. Rotating keys never duplicates work, and a second client in your organization sees none of the first client's results.
Executions
An execution is one call to one operation. The flow:
- Submit.
POST /executionsvalidates the input, reserves the price from your balance and returns202 accepted. - Run. A worker calls the provider. If it fails or rate limits, the next provider is tried. The reservation is released if nothing succeeds.
- Read.
GET /executions/{id}returns the status and the result. Results of public reads can be served from a shared cache.
Request fields:
| Field | Type | Notes |
|---|---|---|
capability | string | Operation id, for example web.search. |
version | integer | Operation version from discovery. |
credential.mode | string | managed or customer. |
input | object | Validated against the operation's schema. |
idempotency_key | string | Your own unique id for this job. |
budget.max_micro_usd | integer | Hard cap. 1 USD is 1,000,000 micro-USD. |
deadline_ms | integer | Optional. Give up after this long. |
Requests are decoded strictly. A field naming an organization, role, wallet or application returns 400 invalid_input. Scope comes from your key and nowhere else.
Idempotency and budgets
History is keyed by (client, capability, idempotency_key). Send the same key again and you get the original execution back, with no second charge.
- Generate the key before the first attempt and reuse it on every retry.
- On
503or a timeout, retry with the same key. The work may already be accepted. - Never retry an uncertain submission with a new key.
budget.max_micro_usdis required on every call. The price is fixed, so you know the maximum cost before you send.
Errors
Errors are deliberately generic. Detail stays in our logs, not your response.
{ "error": { "code": "permission_denied" } }| Status | Code | Meaning |
|---|---|---|
400 | invalid_input | Body failed validation. Unknown fields such as org, roles or wallet_id are rejected, not ignored. |
400 | tls_required | Request did not arrive over HTTPS. |
401 | unauthenticated | Key missing, malformed, unknown, expired or revoked. All look the same on purpose. |
402 | budget_exceeded | Wallet cannot cover the hold. |
402 | key_limit_exceeded | The key spend limit for the day or month would be exceeded. |
403 | permission_denied | The client has no grant for this operation. |
404 | not_found | Unknown id, or an id that belongs to another client. The two are indistinguishable. |
429 | rate_limited | Per-client limit hit. Honor Retry-After. |
503 | unavailable | Retry with the same idempotency_key. The execution may already be accepted. |
Approvals
The external API exposes read operations only. Writes and destructive operations need a human to approve that exact action, and machine keys send no approval. An approval field in a request is rejected. Recurring spend, watches and schedules are not available over this API.
Bring your own key
For SEO operations you can use your own Semrush account instead of ours. Set credential.mode to customer.
- Create the connection in Konnect. The provider key is write-only and never returned.
- Grant it to a client explicitly. A client can hold up to 5 connection grants.
- Each grant is bound to the connection revision. Rotate or disable the connection and the grant goes
staleand authorizes nothing until a human renews it. - Customer-key calls charge nothing on Connect. Your provider bills you directly.
Use with Claude
Connect operations map directly onto Claude tools: each capability already carries a name, a description and a JSON Schema. Load them once, then run the usual tool-use loop.
import os, time, uuid, requests, anthropic
API = "https://api.dashapi.ai/external/v1"
H = {"Authorization": f"Bearer {os.environ['CONNECT_KEY']}"}
client = anthropic.Anthropic()
# 1. Turn Connect capabilities into Claude tools
caps = requests.get(f"{API}/capabilities", headers=H).json()
tools = [{
"name": c["id"].replace(".", "__"), # tool names cannot contain dots
"description": c["description"],
"input_schema": c["input_schema"],
} for c in caps["capabilities"]]
def run(capability, args):
r = requests.post(f"{API}/executions", headers=H, json={
"capability": capability, "version": 1,
"credential": {"mode": "managed"},
"input": args,
"idempotency_key": str(uuid.uuid4()),
"budget": {"max_micro_usd": 50_000}, # hard cap per call
})
r.raise_for_status()
url = f"{API}/executions/{r.json()['id']}"
while True: # poll until terminal
e = requests.get(url, headers=H).json()
if e["status"] not in ("accepted", "running"):
return e
time.sleep(1)
# 2. Standard tool-use loop
messages = [{"role": "user", "content": "Who funded northwind.io?"}]
while True:
resp = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024,
tools=tools, messages=messages)
if resp.stop_reason != "tool_use":
break
messages.append({"role": "assistant", "content": resp.content})
results = []
for b in resp.content:
if b.type == "tool_use":
out = run(b.name.replace("__", "."), b.input)
results.append({"type": "tool_result", "tool_use_id": b.id, "content": str(out)})
messages.append({"role": "user", "content": results})
print(resp.content[0].text)Notes
- Tool names allow letters, digits, underscores and hyphens, so dots in operation ids are swapped for
__and swapped back before the call. - Start with a small allowlist of capabilities. Fewer tools means better selection and a smaller bill.
- Keep
max_micro_usdsmall. The model never sees your balance, but it can call tools in a loop. - Put the key in your server's environment. Never in the prompt.
- Claude Code and Claude Desktop will use the MCP route when it ships. See MCP clients.
Use with ChatGPT
OpenAI API: function calling
Same pattern as Claude. Map each capability to a function and reuse the submit-and-poll helper.
import os, time, uuid, json, requests
from openai import OpenAI
API = "https://api.dashapi.ai/external/v1"
H = {"Authorization": f"Bearer {os.environ['CONNECT_KEY']}"}
client = OpenAI()
caps = requests.get(f"{API}/capabilities", headers=H).json()["capabilities"]
tools = [{"type": "function", "function": {
"name": c["id"].replace(".", "__"),
"description": c["description"],
"parameters": c["input_schema"],
}} for c in caps]
# run() is the same submit-and-poll helper as in the Claude guide.
messages = [{"role": "user", "content": "Find the CTO of northwind.io"}]
while True:
msg = client.chat.completions.create(model="gpt-5", messages=messages, tools=tools).choices[0].message
messages.append(msg)
if not msg.tool_calls:
break
for call in msg.tool_calls:
out = run(call.function.name.replace("__", "."), json.loads(call.function.arguments))
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(out)})
print(msg.content)Custom GPT: Actions
- In the GPT editor, open Configure, then Create new action.
- Import the contract from
https://raw.githubusercontent.com/DashAPI-ai/dashapi-connect/main/openapi/external.yaml. - Set authentication to API Key, type Bearer, and paste your
dck_key. - Keep the action list short. Actions can see only what you expose, and ChatGPT sends requests from OpenAI servers, so use a key with a spend limit.
Use a dedicated client and a spend limit for any key that lives inside a third-party product. If it leaks, disable the client in Konnect.
MCP clients
Status. The Connect MCP adapter is built and tested but not yet exposed on the public listener. Public authentication ships first. The tool surface below is final, and the connection details will be published here at launch.
When live, Claude Desktop, Claude Code, Cursor and any other MCP client will see four meta-tools instead of 300+ individual ones, which keeps the model's context small.
capability_search find operations by id substring (limit 50)
capability_describe schemas, fixed price, credential modes
capability_execute submit an execution, same envelope as REST
execution_get poll an execution by idExample capability_execute arguments:
{
"name": "capability_execute",
"arguments": {
"capability": "person.enrich",
"version": 1,
"credential": { "mode": "managed" },
"input": { "email": "ada@northwind.io" },
"idempotency_key": "job-001",
"budget": { "max_micro_usd": 100000 },
"deadline_ms": 30000
}
}- Transport is sessionless HTTP POST with JSON responses.
- There is no
approvedflag. Writes still need a human approval bound to the action. - Every call is audited with transport
mcp.
Rotate keys
Each client holds up to five live keys, so rotation never needs downtime.
# 1. create a second key in Konnect, deploy it to your server
# 2. confirm traffic uses the new key
# 3. revoke the old key
#
# Revoking stops new requests at once. It does NOT cancel work already accepted.
# To stop a client entirely, disable the client.Endpoints
Base URL https://api.dashapi.ai/external/v1
/capabilitiesOperations this key can call, with schemas and fixed prices.
/executionsSubmit an execution. Returns 202 with an id.
/executions/{id}Read status and result of one of your executions.
/billing/balanceOrganization balance snapshot. Needs full or billing_only access.
/billing/usageSpend by calling application and API key.
Full schemas live in external.yaml. The repository also ships a single-file bundle for client generators: openapi/bundled.yaml.
Limits
| Limit | Value |
|---|---|
| Clients per organization | 50 |
| Live keys per client | 5 |
| Grants per client | 128 |
| Customer connection grants per client | 5 |
| Maximum key lifetime | 2 years |
| Request body | 1 MiB |
| Pagination | 1 to 100, default 50 |
Requests are rate limited per client. On 429, wait for Retry-After seconds.
Self-hosting
Connect is open source. Run the container with PostgreSQL, apply migrations with connect migrate, and register your applications with the audited connect admin CLI. The repository README covers configuration, the development PKI and health checks.