On this site

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 once

2. 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_required before 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:

  1. Submit. POST /executions validates the input, reserves the price from your balance and returns 202 accepted.
  2. Run. A worker calls the provider. If it fails or rate limits, the next provider is tried. The reservation is released if nothing succeeds.
  3. Read. GET /executions/{id} returns the status and the result. Results of public reads can be served from a shared cache.

Request fields:

FieldTypeNotes
capabilitystringOperation id, for example web.search.
versionintegerOperation version from discovery.
credential.modestringmanaged or customer.
inputobjectValidated against the operation's schema.
idempotency_keystringYour own unique id for this job.
budget.max_micro_usdintegerHard cap. 1 USD is 1,000,000 micro-USD.
deadline_msintegerOptional. 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 503 or 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_usd is 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" } }
StatusCodeMeaning
400invalid_inputBody failed validation. Unknown fields such as org, roles or wallet_id are rejected, not ignored.
400tls_requiredRequest did not arrive over HTTPS.
401unauthenticatedKey missing, malformed, unknown, expired or revoked. All look the same on purpose.
402budget_exceededWallet cannot cover the hold.
402key_limit_exceededThe key spend limit for the day or month would be exceeded.
403permission_deniedThe client has no grant for this operation.
404not_foundUnknown id, or an id that belongs to another client. The two are indistinguishable.
429rate_limitedPer-client limit hit. Honor Retry-After.
503unavailableRetry 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 stale and 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.

claude_agent.py
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_usd small. 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.

openai_agent.py
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

  1. In the GPT editor, open Configure, then Create new action.
  2. Import the contract from https://raw.githubusercontent.com/DashAPI-ai/dashapi-connect/main/openapi/external.yaml.
  3. Set authentication to API Key, type Bearer, and paste your dck_ key.
  4. 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 id

Example 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 approved flag. 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

GET/capabilities

Operations this key can call, with schemas and fixed prices.

POST/executions

Submit an execution. Returns 202 with an id.

GET/executions/{id}

Read status and result of one of your executions.

GET/billing/balance

Organization balance snapshot. Needs full or billing_only access.

GET/billing/usage

Spend 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

LimitValue
Clients per organization50
Live keys per client5
Grants per client128
Customer connection grants per client5
Maximum key lifetime2 years
Request body1 MiB
Pagination1 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.

View on GitHub Self-host guide