Knowledge Base

Every agent has a collection of knowledge entries — chunks of information the agent can query at runtime to respond with data specific to your business (manuals, policies, FAQs, product sheets, etc.).

When you upload a file or ingest a URL, Platica handles the processing automatically: it extracts the content, generates a title and description if you didn't provide them, splits it into chunks if it's very long, deduplicates if the file already existed, and indexes everything so the agent can search it.

List Entries

GET https://api.platica.mx/v1/agents/{agentId}/knowledge

URL parameters

Query parameters

Response

{
  "count": 1,
  "knowledge": [
    {
      "id": "FXjQXMr3...",
      "name": "get_politicas_devolucion_a1b2c3",
      "topic": "Políticas de devolución",
      "description": "Documento oficial v2.3 con plazos, condiciones y excepciones.",
      "status": "active",
      "fileType": "pdf",
      "fileName": "manual.pdf",
      "lastUpdate": "2026-05-28T06:14:21.000Z"
    }
  ]
}

Get Entry

GET https://api.platica.mx/v1/agents/{agentId}/knowledge/{knowledgeId}

URL parameters

Response

Returns the full entry, including the already-processed content.

Create from URLs

When the file is already publicly hosted (Firebase Storage, S3, etc.), reference it by URL and Platica downloads and processes it.

POST https://api.platica.mx/v1/agents/{agentId}/knowledge

URL parameters

Request body

{
  "files": [
    {
      "fileUrl": "https://storage.googleapis.com/.../manual.pdf",
      "fileName": "manual.pdf",
      "fileType": "pdf",
      "topic": "Manual del producto",
      "description": "Manual oficial v2.3"
    }
  ],
  "setActive": true
}

Response

{
  "status": "success",
  "message": "Knowledge entries created",
  "data": {
    "totalFiles": 1,
    "successful": 1,
    "failed": { "count": 0, "files": [] }
  }
}

Create from text

If you don't have a file, create the entry straight from raw text by sending content instead of fileUrl. It's the same endpoint POST .../knowledge; only the contents of files[] change:

{
  "files": [
    {
      "fileName": "politica-devoluciones.txt",
      "fileType": "txt",
      "content": "Aceptamos devoluciones dentro de los 30 días posteriores a la compra...",
      "topic": "Devoluciones",
      "description": "Política de devoluciones"
    }
  ],
  "setActive": true
}

With content, Platica skips the download and parsing: it uses the text as-is. If you send topic and description, automatic AI generation is skipped; if you omit them, they are generated from the text. The response is identical to create from URLs .

Upload Files

To upload the binary directly without pre-hosting, send a multipart request to the upload endpoint. Platica stores it, makes it reachable via a public URL, and returns that URL so you can pass it to create from URLs .

POST https://api.platica.mx/v1/agents/{agentId}/knowledge/upload

URL parameters

Request body

Content-Type: multipart/form-data with one or more files fields:

curl -X POST https://api.platica.mx/v1/agents/{agentId}/knowledge/upload \
  -H "Authorization: Bearer pl_key_..." \
  -F "files=@manual.pdf" \
  -F "files=@politicas.docx"

Limit: 20 MB per multipart request.

Response

{
  "status": "success",
  "message": "Files uploaded",
  "data": {
    "success": true,
    "uploaded": [
      {
        "fileName": "manual.pdf",
        "fileUrl": "https://storage.googleapis.com/.../manual.pdf",
        "fileType": "pdf",
        "fileSize": 481923
      }
    ]
  }
}

Ingest Web URLs

Ingests the content of web pages, converts them to text, and creates knowledge entries with an automatically generated title and description.

POST https://api.platica.mx/v1/agents/{agentId}/knowledge/web

URL parameters

Request body

{
  "urls": [
    "https://docs.miempresa.com/faq",
    "https://miempresa.com/politicas/devoluciones"
  ]
}

Response

{
  "status": "success",
  "message": "Web pages ingested",
  "data": {
    "totalUrls": 2,
    "successful": 2,
    "failed": { "count": 0, "details": [] }
  }
}

Update Entry

Updates an existing entry: appends text to the content, replaces it entirely, changes metadata or status, or reprocesses the original source.

PATCH https://api.platica.mx/v1/agents/{agentId}/knowledge/{knowledgeId}

URL parameters

Request body

Change status:

{ "status": "active" }

Append text to the end of the content (without rewriting what's already there):

{ "appendContent": "Nuevo párrafo que se agrega al final." }

Replace the content directly (overwrites all the text). You can also update topic and description:

{ "content": "Nuevo contenido completo de la entrada...", "topic": "Devoluciones", "description": "Política actualizada" }

Reprocess the original source (re-extracts and regenerates metadata):

{ "reprocess": true }

Response

{
  "status": "success",
  "message": "Knowledge entry updated"
}

Delete Entry

Removes an entry from the agent's knowledge base. The agent can no longer query it.

DELETE https://api.platica.mx/v1/agents/{agentId}/knowledge/{knowledgeId}

URL parameters

Response

{
  "status": "success",
  "message": "Knowledge entry deleted"
}

Reprocess Entry

Reprocesses the original source of an entry (downloads the file or URL again, re-extracts the content, and regenerates the metadata).

POST https://api.platica.mx/v1/agents/{agentId}/knowledge/{knowledgeId}/reparse

URL parameters

Request body

{ "web": false }

{ "source": "web" } is also accepted as an alias.

Response

{
  "status": "success",
  "message": "Knowledge entry reparse queued"
}

Notes

• If you upload a file identical to an existing entry (same content), the system deduplicates and does not create a new one.
• For very long files, the content is split across several related entries to keep search quality high.