Knowledge bases

A knowledge base is a set of documents an AI agent searches while it talks: hours, prices, service areas, policies. The agent answers from it instead of guessing.

An id that belongs to another account answers 404, the same as one that doesn't exist.

Routes

List knowledge bases

curl "https://api-v2.dropcowboy.com/document/public/knowledge-bases?search=faq" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

data is an array of knowledge bases, shaped as below. meta.total, meta.limit and meta.offset describe the page (see Pagination).

Create a knowledge base

Set ai_audience to public for a knowledge base a receptionist or an AI call answers from. Agents search public knowledge bases unless you tell them otherwise (see Attach to an agent).

curl -X POST https://api-v2.dropcowboy.com/document/public/knowledge-bases \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "content-type: application/json" \
  -d '{
    "name": "Customer FAQ",
    "description": "Hours, pricing and service area for callers.",
    "ai_audience": "public"
  }'

The route answers 201:

{
  "data": {
    "knowledge_base_id": "9d3f6a2c-4e8b-4b1d-a7c5-2f6e9b3d8a14",
    "name": "Customer FAQ",
    "description": "Hours, pricing and service area for callers.",
    "ai_audience": "public",
    "status": "active",
    "stats": { "document_count": 0, "ready_count": 0, "failed_count": 0, "chunk_count": 0 },
    "created_at": 1774041600000,
    "updated_at": 1774041600000
  },
  "meta": { "request_id": "8a2f6c1e-4d9b-4e7a-b3c5-6f1d8e2a9c47" }
}

Timestamps are epoch milliseconds. stats counts the documents and how many are ready or failed.

Get a knowledge base

GET /document/public/knowledge-bases/{knowledge_base_id} returns the knowledge base, shaped as above.

Update a knowledge base

Send only the fields to change: name, description, ai_audience, or status (active or archived). An archived knowledge base drops out of the default list.

curl -X POST https://api-v2.dropcowboy.com/document/public/knowledge-bases/9d3f6a2c-4e8b-4b1d-a7c5-2f6e9b3d8a14 \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "content-type: application/json" \
  -d '{ "ai_audience": "public" }'

Add a document

One route, three ways. The fields you send pick the way. Each answers 201.

Inline markdown

Best for FAQs you already have as text. Send title and markdown, up to 1 MB.

curl -X POST "https://api-v2.dropcowboy.com/document/public/knowledge-bases/$KB_ID/documents" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "content-type: application/json" \
  -d '{
    "title": "Hours and location",
    "markdown": "# Hours\n\nMonday to Friday, 8am to 6pm. Saturday, 9am to 1pm. Closed Sunday.\n\n# Location\n\n100 Example Street, Springfield."
  }'

From a URL

Send source_url, a public http or https address up to 2048 characters, with an optional title. Drop Cowboy® downloads the file, up to 25 MB.

{
  "source_url": "https://www.example.com/files/price-list.pdf",
  "title": "Price list"
}

If the server labels the file with a supported type, that type wins. Otherwise send mime_type too.

Upload a file

Three steps, for files up to 25 MB.

1. Ask for an upload ticket:

{
  "title": "Price list",
  "filename": "price-list.pdf",
  "mime_type": "application/pdf",
  "byte_size": 184320
}

{
  "data": {
    "knowledge_document_id": "5b8e1c4f-7a2d-4f9e-b3c6-8d1a5e2f7b40",
    "knowledge_document": { "ingest_status": "pending", "upload_confirmed": false },
    "upload": {
      "method": "PUT",
      "url": "https://uploads.example.com/knowledge/price-list.pdf?signature=example-signature",
      "headers": { "Content-Type": "application/pdf" },
      "max_bytes": 26214400
    }
  },
  "meta": { "request_id": "4d6f8a1c-3e5b-4c7d-9f2a-6b8d1e3f5a70" }
}

2. PUT the file to upload.url with exactly the headers in upload.headers. The URL is signed for that Content-Type and rejects any other. It expires after 48 hours. If it has expired, get a new upload URL.

curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @price-list.pdf

3. Confirm the upload.

Supported types

The file extension must match mime_type. Anything else answers 415.

Confirm an upload

Confirm after the PUT succeeds. The route answers 200 and processing starts.

curl -X POST \
  "https://api-v2.dropcowboy.com/document/public/knowledge-bases/$KB_ID/documents/$DOC_ID/uploaded" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

A refused duplicate or oversized file marks the document failed, with the reason in ingest_error. A later successful confirm clears it. To give up instead, delete the document.

Get a new upload URL

Use this when the upload URL expired before you used it, or when a confirm was refused and you want to send different bytes.

curl -X POST \
  "https://api-v2.dropcowboy.com/document/public/knowledge-bases/$KB_ID/documents/$DOC_ID/upload-url" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

The route answers 200 with the same shape as the upload ticket. PUT and confirm exactly as before. A document marked failed by a refused confirm goes back to pending.

The route is safe to retry, and earlier URLs keep working until they expire. It works only until a confirm succeeds. After that, and for markdown and URL documents, it answers 409 (already-confirmed). To replace a confirmed document, delete it and add it again.

List documents

Every document is processed into searchable passages after it's added. Poll this list and check ingest_status. Only ready documents are searched.

curl "https://api-v2.dropcowboy.com/document/public/knowledge-bases/$KB_ID/documents?limit=100" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

Each document carries knowledge_document_id, knowledge_base_id, title, filename, mime_type, byte_size, source, ai_audience, upload_confirmed, ingest_status, ingest_error, chunk_count, created_at and updated_at.

Search a knowledge base

Before you attach a knowledge base, ask it the questions callers will ask. query is up to 1000 characters.

curl -X POST "https://api-v2.dropcowboy.com/document/public/knowledge-bases/$KB_ID/query" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "content-type: application/json" \
  -d '{ "query": "What are your hours on Saturday?" }'

{
  "data": {
    "query": "What are your hours on Saturday?",
    "results": [
      {
        "chunk_id": "7f4c2a9e-3b1d-4e6a-8c5f-9d2b7e1a4c36",
        "knowledge_base_id": "9d3f6a2c-4e8b-4b1d-a7c5-2f6e9b3d8a14",
        "knowledge_document_id": "2c7a9e4b-1d6f-4a3e-8b5c-7f2d9a6e1c83",
        "chunk_index": 0,
        "text": "Monday to Friday, 8am to 6pm. Saturday, 9am to 1pm. Closed Sunday.",
        "score": 0.87,
        "heading": "Hours",
        "section_path": "Hours",
        "page": null
      }
    ]
  },
  "meta": { "request_id": "6e8a1c3f-5b7d-4e9a-8c2f-1d3b5e7a9c42" }
}

These are the passages an agent would retrieve, best first. If the right passage is missing, improve the document before you attach it.

Delete a document

curl -X DELETE "https://api-v2.dropcowboy.com/document/public/knowledge-bases/$KB_ID/documents/$DOC_ID" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

The route returns {"knowledge_document_id": "...", "deleted": true}.

Delete a knowledge base

curl -X DELETE "https://api-v2.dropcowboy.com/document/public/knowledge-bases/$KB_ID" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

The route returns {"knowledge_base_id": "...", "deleted": true}. Take the id out of any agent's think.knowledge and publish the agent again.

Attach to an agent

Set think.knowledge on the agent, then publish it:

{
  "think": {
    "prompt_spec": { "role": "Receptionist for Example Dental" },
    "knowledge": {
      "mode": "selected",
      "knowledge_base_ids": ["9d3f6a2c-4e8b-4b1d-a7c5-2f6e9b3d8a14"],
      "audience": "public"
    }
  }
}

Updating think replaces the whole object, so send the agent's existing think with knowledge added. Update an agent has a complete example.

Publishing checks the selected knowledge bases. It fails with 400 (unusable_knowledge_base) if their content reads like instructions for your staff ("click Settings, then...") rather than answers for callers, or tells callers to check an app for your hours without stating them. Write documents the way you want the agent to speak.

Errors

The errors specific to knowledge bases are below. For the error format and everything else, see Responses, errors and limits.

A token issued for a signed-in user is checked against that user's role. API keys never are. A denial has detail You do not have permission to use Knowledge Bases. on reads and You do not have permission to manage Knowledge Bases. on changes:

{
  "type": "https://api-v2.dropcowboy.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to manage Knowledge Bases.",
  "instance": "/document/public/knowledge-bases",
  "request_id": "3c5e7a9b-1d2f-4a6c-8e0b-5f7d9a1c3e62"
}

If the role can't be looked up, the answer is 500. Retry.