Ricky logorickyDocs

Upload a file

POST
/knowledge/files

Begins an upload in three steps: this call answers the file, uploading, and an upload_url; PUT the bytes there; then call POST /knowledge/files/{file_id}/complete.

Scope: knowledge:write.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An organization API key, rky_live_…, created in Settings → API. Send it only from a server.

Header Parameters

Idempotency-Key?string

Optional. A value you choose, unique per logical write, 8–200 characters: a UUID or an ID from your system such as order-10482-ready. Retrying with the same key and body replays the first response instead of repeating the write.

Length8 <= length <= 200

Request Body

application/json
  1. body

Begins an upload. Ricky answers where to PUT the bytes.

title*string

Title the agents see.

Length1 <= length <= 160
description?string

When the agents should use it.

Lengthlength <= 2000
Default""
filename*string

File name, with its extension.

Length1 <= length <= 255
mime_type*string

File type: PDF, Word or Excel up to 100 MB; JPEG or PNG up to 5 MB.

Value in"application/pdf""application/vnd.openxmlformats-officedocument.wordprocessingml.document""application/vnd.openxmlformats-officedocument.spreadsheetml.sheet""image/jpeg""image/png"
size_bytes*integer

Exact size of the file you will upload.

Range1 <= value <= 9007199254740991

Response Body

Success.

application/json
  1. response
data*

A file waiting for its bytes, and where to put them.

curl -X POST 'https://getricky.ai/api/v1/knowledge/files' \  -H 'Idempotency-Key: order-10482-ready' \  -H 'Content-Type: application/json' \  -d '{  "title": "Catálogo de lentes 2026",  "filename": "catalogo-2026.pdf",  "mime_type": "application/pdf",  "size_bytes": 482133}'
{  "data": {    "file": {      "id": "f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c",      "title": "Catálogo de lentes 2026",      "description": "Precios y modelos vigentes.",      "filename": "catalogo-2026.pdf",      "mime_type": "application/pdf",      "size_bytes": 482133,      "status": "uploading",      "consult_enabled": true,      "send_enabled": true,      "page_count": 12,      "preview": "Catálogo 2026. Lentes de sol…",      "extraction_error": null,      "download_url": null,      "created_at": "2026-10-14T15:30:00.000Z",      "updated_at": "2026-10-14T15:30:00.000Z"    },    "upload_url": "https://storage.example.com/upload/sign/media/d9e0f1a2-b3c4-4d5e-8f6a-7b8c9d0e1f2a/knowledge/f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c.pdf?token=…"  }}