For Builders

REST API

The REST API is the main door for integrating Daguito into your code. You authenticate with a Bearer token and, depending on which credential you use, you can deploy flows idempotently, feed and query knowledge bases, and read your organization's usage analytics. This page documents only the public, verified endpoints.

Base URL and authentication

Every call hits a single production endpoint:

https://api.daguito.com

Each request authenticates with a Bearer token in the Authorization header:

Authorization: Bearer <credencial>

There are three credential types, each with its own prefix:

• dgsk_acc_ — account key, scoped to the whole organization. Use it to deploy flows and read analytics.
• dgpk_flow_ — public flow key, restricted to a specific flow.
• dgsk_wh_ — webhook token, ephemeral and tied to a webhook for client-side streaming.

Every token is the prefix plus 32 random base62 characters. Daguito stores only the SHA-256 hash, never the plaintext.

Account key management

Account keys are created and revoked from the dashboard, not with another API key. The endpoints below are the same ones the dashboard calls: they authenticate with your admin session (an org-owner JWT in the Authorization header), not with a dgsk_acc_ token. Each organization can hold up to 10 active keys.

List keys

Returns the organization's keys without the plaintext value:

curl -X GET https://api.daguito.com/v1/account/api-keys \
  -H 'Authorization: Bearer <session-jwt>' \
  -H 'Content-Type: application/json'

Create a key

Create a key with a name and, optionally, a monthly_budget_micro_usd (monthly spend limit in micro-USD). Responds with 201 and includes the plaintext value once.

curl -X POST https://api.daguito.com/v1/account/api-keys \
  -H 'Authorization: Bearer <session-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "production", "monthly_budget_micro_usd": 100000000}'

In the example, 100,000,000 micro-USD equals a 100 USD monthly budget.

Revoke a key

Revoke a key by its id. Responds with 204 and no body.

curl -X DELETE https://api.daguito.com/v1/account/api-keys/<id> \
  -H 'Authorization: Bearer <session-jwt>'

Response shape

Each key is represented like this (without the plaintext value). key_prefix is the first 14 characters of the token — enough to identify it in a list without exposing the whole thing:

{
  "id": "uuid",
  "name": "production",
  "key_prefix": "dgsk_acc_AbC1x",
  "monthly_budget_micro_usd": 100000000,
  "current_mtd_micro_usd": 45230000,
  "created_at": "2026-01-15T10:30:00Z",
  "last_used_at": "2026-06-07T14:22:15Z",
  "revoked_at": null
}

Flows API

Deploy flows idempotently from your code or your CI pipeline. Resubmitting the same slug updates the flow instead of duplicating it.

Create or update an agent

POST /v1/flows/upsert-agent creates an agent with its trigger from a template (slug, provider, model, system_prompt, tools). Requires a dgsk_acc_ key.

curl -X POST https://api.daguito.com/v1/flows/upsert-agent \
  -H 'Authorization: Bearer dgsk_acc_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "my_agent",
    "name": "My Agent",
    "model": "meta-llama/llama-3.3-70b-instruct",
    "system_prompt": "You are a helpful assistant",
    "temperature": 0.7,
    "max_tokens": 1024
  }'

Upload a custom flow

POST /v1/flows/upsert uploads a full graph. The body carries slug, name, and a graph object with nodes and edges (plus an optional trigger_type). Accepts a dgsk_acc_ key or an sk_dgt_ key with flow:admin scope.

Resolve a flow's webhook

GET /api/sdk/flows?slug=<slug> returns the flow_id and the webhook token your client uses for streaming. Requires an sk_dgt_ key with flow:run scope.

curl -X GET 'https://api.daguito.com/api/sdk/flows?slug=my_agent' \
  -H 'Authorization: Bearer sk_dgt_...' \
  -H 'Content-Type: application/json'

Knowledge API

Feed your knowledge bases and query them with the same Knowledge Base pipeline the platform uses. The org_id is always derived from the token, never from the request body.

Ingest text

POST /api/sdk/knowledge/sources/:id/text ingests text with optional metadata. Requires an sk_dgt_ key with kb:write scope.

curl -X POST https://api.daguito.com/api/sdk/knowledge/sources/<id>/text \
  -H 'Authorization: Bearer sk_dgt_...' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Devoluciones en 30 dias.", "metadata": {"lang": "es"}}'

Search a base

POST /api/sdk/knowledge/search retrieves relevant chunks with query, session_id, and optional source_ids, top_k, enable_rewrite, enable_rerank, and enable_cache. Requires an sk_dgt_ key with kb:read scope.

curl -X POST https://api.daguito.com/api/sdk/knowledge/search \
  -H 'Authorization: Bearer sk_dgt_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "how to reset password",
    "top_k": 5,
    "enable_rerank": true,
    "enable_cache": true
  }'

Per-resource scope is enforced on every endpoint: the key must hold the right action permission and be authorized for the requested bases. If a source does not exist or belongs to another organization, the response is 404 (so it doesn't leak existence); if the key lacks scope, it's 403.

Monitoring and usage

GET /v1/org/analytics returns a usage snapshot for your organization (today's counters plus the outbound count for the last 24 hours). Requires a dgsk_acc_ key.

curl -X GET https://api.daguito.com/v1/org/analytics \
  -H 'Authorization: Bearer dgsk_acc_...' \
  -H 'Content-Type: application/json'

The response includes:

• LLM — requests, tokens, and cost in USD.
• Messages — inbound for today and outbound over the last 24 hours.
• HTTP — total calls and breakdown by path.
• Budget — month-to-date limits and spend, at both the organization and key level.

Error handling

Errors always come back as JSON with a single text field:

{
  "error": "API key required"
}

Status codes:

• 400 — validation failed (e.g., malformed slug, name too long, or invalid JSON).
• 401 — missing, invalid, or expired key.
• 403 — valid key but missing the required scope (action or resource).
• 404 — resource not found or access denied by organization (so it doesn't reveal existence).
• 500 — unexpected server error.

Rate limiting

Rate limits apply only to widget endpoints (chat, form, cart):

• 10 messages every 60 seconds per session.
• 100 messages every 3600 seconds per IP.

They are implemented with sliding-window counters. When the limit is exceeded, the response tells you how long to wait, in milliseconds:

{
  "allowed": false,
  "retry_after_ms": 4200
}

SDK and admin endpoints have no published per-request limits; control happens through spend budgets.

Credentials and scopes

Each credential has a distinct purpose and scope:

• Account keys (dgsk_acc_): org-wide scope, created by the owner. Used to deploy flows (upsert-agent / upsert) and read usage analytics.
• SDK keys (sk_dgt_): restricted to a flow or a base, created from the dashboard. These are the keys that operate on knowledge and resolve webhooks. They declare their scope by action (kb:read, kb:write, flow:run, flow:admin) and by resource.
• Webhook tokens (dgsk_wh_): ephemeral and tied to a specific webhook, for client-side streaming without embedding sensitive credentials.

Scope is enforced in two layers: the middleware checks action scope, and the handler verifies per-resource scope once the target resource is resolved (a null value means all resources in the organization).

What's next?