Ingest Knowledge

POST /v2/memory/knowledge/ingest

Ingest Knowledge

cURL

curl --request POST \
  --url https://api.velt.dev/v2/memory/knowledge/ingest \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "source": "<string>",
    "file": {},
    "fileRef": "<string>",
    "mimeType": "<string>",
    "organizationId": "<string>",
    "documentId": "<string>"
  }
}
'

{
  "result": {
    "status": "processing",
    "sourceId": "src_9a8...",
    "message": "Knowledge ingestion task enqueued."
  }
}

Use this API to submit reference material (guidelines, standards, policy docs) to your Memory knowledge base. Ingestion is asynchronous: the call returns immediately with a sourceId, and conversion, rule extraction, and embedding run in the background. Poll Get Ingest Status until the status is terminal. Supported file types: PDF, CSV, Excel (.xlsx), and plain text.

​

Endpoint

POST https://api.velt.dev/v2/memory/knowledge/ingest

Rate limit: 30 requests per minute per API key.

​

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

​

Body

​

Params

The request is a discriminated union on source: send source: "inline" with a base64 file (decoded size up to 5 MB, 5,242,880 bytes), or source: "fileRef" with a gs:// URI from Get Upload URL (up to 30 MB, 31,457,280 bytes).

data · object · required

Show properties

source · string · required

inline or fileRef.

file · object

Required when source is inline. { base64, mimeType, fileName, fileSize }, and all four sub-fields are required. base64 is the encoded file bytes; fileName is 1 to 255 characters. fileSize is the decoded size in bytes and must itself be at most 5 MB (5,242,880 bytes); the server also re-measures the decoded base64 against the same cap.

fileRef · string

Required when source is fileRef. The gs:// URI returned by Get Upload URL. Pass the same organizationId and documentId you used when calling Get Upload URL; a scope mismatch returns PERMISSION_DENIED, as does a ref that belongs to another workspace. Each fileRef can be ingested only once. An object that was never uploaded, has expired, or was already ingested returns FAILED_PRECONDITION. The 30 MB cap is enforced against the bytes actually uploaded, not against any request field.

mimeType · string

Required when source is fileRef. One of the supported types: application/pdf, text/csv, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, or text/plain. Use the same mimeType you passed to Get Upload URL and set as the upload’s Content-Type header.

organizationId · string

Scope the source to one organization.

documentId · string

Scope the source to one document. Requires organizationId.

On an inline upload, the server verifies file.mimeType against the file’s own bytes. A mismatch, or a text/csv or text/plain file that is not valid UTF-8, returns INVALID_ARGUMENT. This endpoint also rejects unrecognized fields, so a misspelled key returns INVALID_ARGUMENT instead of being ignored.

​

Example Requests

​

Inline (file up to 5 MB)

{
  "data": {
    "source": "inline",
    "file": {
      "base64": "JVBERi0xLjQK...",
      "mimeType": "application/pdf",
      "fileName": "brand-guidelines.pdf",
      "fileSize": 184320
    }
  }
}

​

By reference (file up to 30 MB)

{
  "data": {
    "source": "fileRef",
    "fileRef": "gs://bucket/path/original.pdf",
    "mimeType": "application/pdf"
  }
}

​

Response

Ingestion runs in the background. Poll Get Ingest Status with the returned sourceId until the status is completed or failed.

​

Success Response

{
  "result": {
    "status": "processing",
    "sourceId": "src_9a8...",
    "message": "Knowledge ingestion task enqueued."
  }
}

​

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
  "result": {
    "status": "processing",
    "sourceId": "src_9a8...",
    "message": "Knowledge ingestion task enqueued."
  }
}