Get started
API Reference

API Reference

Complete reference for the Agero API — chat, retrieval, and source management endpoints with interactive code examples.

API Reference

Complete reference for the Agero API — chat, retrieval, and source management endpoints with interactive code examples.

Authentication

API requests authenticate with either header format:

Authorization: Bearer spk_...

or:

x-api-key: spk_...

API keys support three permission types:

PermissionUsed for
chatChat and chat streaming
retrieveRetrieval-only requests
ingestSource management and ingestion

Origin allowlists

If a key has allowed origins configured, the request must include an Origin header that exactly matches one of the configured values. Keys with no allowlist accept requests from any origin.

Error Responses

All errors follow a consistent envelope:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials"
  }
}
CodeStatusMeaning
UNAUTHORIZED401Missing or invalid API key
FORBIDDEN403Origin not allowed for this key
VALIDATION_ERROR400Request body did not match the schema
NOT_FOUND404Resource does not exist or is not accessible
RATE_LIMITED429Per-key rate limit exceeded
LIMIT_EXCEEDED429Plan entitlement limit reached
GONE410Route has moved or is no longer served here
UNSUPPORTED_ATTACHMENT_TYPE400File type not supported by the selected model
ATTACHMENT_TOO_LARGE400Total attachment size exceeds model limit
UNSUPPORTED_TYPE400File type not allowed for upload
FILE_TOO_LARGE400File exceeds the per-type upload size limit
INTERNAL_ERROR500Unexpected server failure

Endpoints

Chat & Retrieval

Send messages, stream responses, and search the knowledge base.

POST
/api/v1/chat

Deprecated — returns 410 GONE. Use POST /api/v1/chat/stream instead for both streaming and non-streaming use cases.

curl -X POST https://your-domain.com/api/v1/chat \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your opening hours?"}'

Request body

{
  "message": "What are your opening hours?",
  "conversationId": "optional",
  "endUserId": "optional"
}

Response

{
  "reply": "We are open 9am–6pm Monday to Friday.",
  "conversationId": "conv_abc123",
  "citations": [
    {
      "title": "FAQ",
      "url": null,
      "similarity": 0.92
    }
  ],
  "media": []
}
POST
/api/v1/chat/stream

Stream a response using Server-Sent Events. Compatible with the Vercel AI SDK client. Send as JSON for text-only, or as multipart/form-data to include file attachments (images, PDFs) for multimodal models.

# Text-only (JSON)
curl -X POST https://your-domain.com/api/v1/chat/stream \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "Tell me about your products"}' \
  --no-buffer

# With file attachments (multipart)
curl -X POST https://your-domain.com/api/v1/chat/stream \
  -H "Authorization: Bearer spk_your_api_key" \
  -F "message=Describe this image" \
  -F "files=@photo.png" \
  --no-buffer

# Multiple files
curl -X POST https://your-domain.com/api/v1/chat/stream \
  -H "Authorization: Bearer spk_your_api_key" \
  -F "message=Compare these documents" \
  -F "files=@report.pdf" \
  -F "files=@chart.png" \
  --no-buffer

Request body

// JSON (text-only)
{
  "message": "Tell me about your products",
  "conversationId": "optional",
  "endUserId": "optional"
}

// multipart/form-data (with files)
// Fields: message, files[] (up to 10), conversationId?, endUserId?

Response

// SSE stream — text deltas, citations, and a final done event
POST
/api/v1/retrieve

Search the knowledge base without AI generation. Useful for custom search UIs.

curl -X POST https://your-domain.com/api/v1/retrieve \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "pricing plans", "topK": 5}'

Request body

{
  "query": "pricing plans",
  "topK": 5,
  "threshold": 0.7
}

Response

{
  "results": [
    {
      "content": "Our plans start at $29/mo...",
      "title": "Pricing",
      "url": "https://example.com/pricing",
      "similarity": 0.94
    }
  ]
}

Sources

Manage knowledge sources programmatically. Requires an API key with the ingest permission.

GET
/v1/sources

List sources with cursor-based pagination. Filter by status or type.

curl https://api.agero.tech/v1/sources?limit=20&status=READY \
  -H "Authorization: Bearer spk_your_api_key"

Request body

// Query params: ?limit=20&status=READY&type=URL&cursor=clx...

Response

{
  "data": {
    "sources": [
      {
        "id": "clx...",
        "type": "URL",
        "name": "Help center",
        "status": "READY",
        "config": {
          "url": "https://help.example.com"
        },
        "latestJob": {
          "id": "clx...",
          "status": "SUCCEEDED",
          "progress": 100
        }
      }
    ],
    "nextCursor": "clx..."
  }
}
POST
/v1/sources

Create a new knowledge source. Supports URL, SITEMAP, FILE, and IMAGE types. Ingestion starts automatically unless autoSync is false.

curl -X POST https://api.agero.tech/v1/sources \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key" \
  -d '{"type":"URL","name":"Help center","config":{"url":"https://help.example.com","maxDepth":3}}'

Request body

{
  "type": "URL",
  "name": "Help center",
  "config": {
    "url": "https://help.example.com",
    "maxDepth": 3
  },
  "autoSync": true
}

Response

{
  "data": {
    "source": {
      "id": "clx...",
      "type": "URL",
      "name": "Help center",
      "status": "PENDING"
    },
    "ingestionJob": {
      "id": "clx...",
      "status": "QUEUED"
    }
  }
}
DELETE
/v1/sources/:id

Delete a source and all its associated documents and chunks.

curl -X DELETE https://api.agero.tech/v1/sources/SOURCE_ID \
  -H "Authorization: Bearer spk_your_api_key"

Request body

// No request body

Response

{
  "data": {
    "id": "clx...",
    "deleted": true
  }
}
POST
/v1/sources/:id/sync

Trigger an ingestion or full re-index for a source. Use force: true for a complete re-index.

curl -X POST https://api.agero.tech/v1/sources/SOURCE_ID/sync \
  -H "Authorization: Bearer spk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"force": false}'

Request body

{
  "force": false
}

Response

{
  "data": {
    "jobId": "clx...",
    "status": "QUEUED",
    "sourceId": "clx..."
  }
}

File Attachments

Send images and documents alongside your chat message in a single request. Just send POST /api/v1/chat/stream as multipart/form-data instead of JSON:

curl -X POST https://your-domain.com/api/v1/chat/stream \
  -H "Authorization: Bearer spk_..." \
  -F "message=What is in this image?" \
  -F "files=@photo.png"

No separate upload step — include the files directly. We detect the type, validate it against the model, and handle the rest.

Supported types: JPEG, PNG, WebP, GIF, PDF. Up to 10 files per message.

Size limits: Images 10 MB, documents 25 MB per file. Total per-message limits vary by model (e.g. 20 MB for OpenAI, 25 MB for Anthropic).

Model compatibility

Not all models support file inputs. If the selected model does not support the attachment type, the API returns a 400 error with code UNSUPPORTED_ATTACHMENT_TYPE. Vision models accept images; some also accept PDFs. Text-only models reject all attachments.

Source Types

When creating sources via POST /v1/sources, use one of the following types:

TypeRequired config fieldsNotes
URLconfig.urlOptional: maxDepth, includePatterns, excludePatterns
SITEMAPconfig.sitemapUrl or config.urlOptional: includePatterns, excludePatterns
FILEconfig.fileUrlOptional: fileName
IMAGEconfig.fileUrlOptional: fileName
BULK_UPLOADVariesTypically created via the dashboard

Idempotency

Pass an Idempotency-Key header on POST /v1/sources to safely retry requests. Matching keys within 24 hours return the original response without creating duplicates.

Related Docs

API Keys

Create and manage keys for chat, retrieve, and ingest use cases.

Tools

Enable built-in tools and create custom HTTP tools for your agent.

Sources

Add and monitor the content your agent retrieves from.

Last updated: May 2026