Grill API Reference

Reference for every /grill/* endpoint on POMA AI API v3.

• Base URL: https://api.poma-ai.com/v3
• Auth: Authorization: Bearer <project-api-key> for every endpoint. The project must have product: "grill".
• Spec: Swagger UI

For higher-level walkthroughs, see Ingestion, Retrieval, RetrievalContext format, and Document management.

Endpoint summary

Method	Path	Purpose
POST	/grill/ingest	Submit a file for ingestion into the project's Grill namespace.
POST	/grill/search	Hybrid search across the namespace; returns prompt-ready context.
POST	/grill/searchInDoc	Same as /grill/search but doc_filter is required.
GET	/grill/docs	List documents in the namespace.
GET	/grill/docs/{docId}	Get metadata for one document.
DELETE	/grill/docs/{docId}	Remove a document's vectors and storage.

The standard /jobs/{job_id}/... endpoints (status, delete) are reused by Grill ingest jobs — they are documented under the main API.

---

POST /grill/ingest

Create an ingestion job. The body is raw bytes (application/octet-stream); the filename is carried in Content-Disposition. Multipart is not accepted.

Request headers

Header	Required	Notes
Authorization	yes	Bearer <project-api-key>.
Content-Type	yes	application/octet-stream.
Content-Disposition	yes	attachment; filename="<name>.<ext>". The extension drives parser selection.

Response (201 Created) — PublicJob

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2026-04-30T10:00:00Z",
  "properties": {
    "file": { "filename": "manual.pdf", "size": 1048576 }
  }
}

Status codes

Status	Meaning
201	Job created. Poll status with GET /jobs/{job_id}/status or stream via GET /status/v1/jobs/{job_id}.
400	Bad request (missing Content-Disposition, unsupported MIME, empty body).
401	Missing/invalid Bearer token.
403	Multipart submitted, or the project's product is primecut.
500	Server error.

See Ingestion for the full lifecycle.

---

POST /grill/search

Hybrid retrieval. Returns a prompt-ready RetrievalContext.

Request body — GrillSearchRequest

Field	Type	Required	Description
query	string	yes	Natural-language query.
doc_filter	string	no	Optional document id filter. Use /grill/searchInDoc when this is required.
exclude_doc_ids	array of string	no	Doc ids to exclude from results (max 100). Useful in agent loops to avoid re-citing docs already shown.
return_assets	boolean	no	Include asset references in matched chunks.
return_page_images	boolean	no	Include page image references.
min_relevance	float 0..1	no	Drop hits below this score.
max_tokens	integer	no	Token budget for the rendered context block. Sandwich-aware truncation.

Result count is bounded server-side by relevance and the token budget — there is no top_k parameter.

Response (200 OK) — RetrievalContext

{ "context": "<doc id=\"…\">…</doc>" }

The context field is the entire response — see RetrievalContext format for the grammar.

Status codes

Status	Meaning
200	OK.
400	Validation error or upstream Grill 400.
401	Missing/invalid token, or upstream 401.
403	Upstream Grill 403.
404	doc_filter references an unknown doc.
502	Other upstream Grill / proxy error.
503	Cannot reach the Grill backend.

---

POST /grill/searchInDoc

Same shape as /grill/search, but doc_filter is required and must be non-empty. Use this when you want server-side enforcement that retrieval stays inside one document.

Request body — GrillSearchInDocRequest

Field	Type	Required	Description
query	string	yes	Natural-language query.
doc_filter	string	yes	Document id to restrict search to.
exclude_doc_ids	array of string	no	Doc ids to exclude (max 100).
return_assets	boolean	no	Include asset references.
return_page_images	boolean	no	Include page image references.
min_relevance	float 0..1	no	Score threshold.
max_tokens	integer	no	Token budget.

Same as /grill/search: result count is bounded by relevance and the token budget; there is no top_k.

Response (200 OK) — RetrievalContext (identical to /grill/search).

Status codes

Status	Meaning
200	OK.
400	Missing query, missing/empty doc_filter, or upstream 400.
401	Missing/invalid token.
403	Upstream Grill 403.
404	Doc not found in this project's namespace.
502	Upstream / proxy error.
503	Grill backend unreachable.

---

GET /grill/docs

List documents in the project's namespace.

Response (200 OK) — ListDocsResponse

{
  "namespace": "project_docs_rag_4f2",
  "total_documents": 3,
  "documents": [ DocInfo, … ]
}

Field	Type	Description
namespace	string	Project namespace identifier in the Grill backend.
total_documents	integer	Count of documents in the namespace.
documents	array	DocInfo entries (see below).

Status codes

Status	Meaning
200	OK.
401	Missing/invalid token.
403	Upstream Grill 403.
404	Upstream Grill 404.
502 / 503	Upstream issues.

---

GET /grill/docs/{docId}

Fetch metadata for one document.

Path parameters

Name	Type	Description
docId	string	The exact doc_id returned by /grill/docs.

Response (200 OK) — DocInfo

Field	Type	Description
doc_id	string	Stable identifier within the namespace.
title	string	Detected title (filename fallback).
language	string	BCP-47 language code.
filename	string	Original ingest filename.
pages	integer	Source page count.
chunkset_count	integer	Chunksets produced.
chunk_count	integer	Chunks produced.
image_count	integer	Detected figures/images.
table_count	integer	Detected tables.
ingested_at	string (RFC 3339)	Job completion time.
source_job_id	string	job_id of the originating /grill/ingest.

Status codes

Status	Meaning
200	OK.
400	Empty docId.
401	Missing/invalid token.
403	Upstream Grill 403.
404	Doc not found in this namespace.
502 / 503	Upstream issues.

---

DELETE /grill/docs/{docId}

Remove a document's vectors and storage from the namespace. Project, key, and other documents are unaffected.

Path parameters

Name	Type	Description
docId	string	Document to delete.

Response (200 OK) — DeleteDocResponse

Field	Type	Description
doc_id	string	Echoes the deleted docId.
vectors_deleted	integer	Vector count removed from the namespace.
storage_deleted	boolean	Whether stored bytes (assets, page images) were removed.

Status codes

Status	Meaning
200	OK.
400	Empty docId.
401	Missing/invalid token.
403	Upstream Grill 403.
404	Doc not found in this namespace.
502 / 503	Upstream issues.

---

Schemas (canonical shapes)

These are the same definitions used by the OpenAPI v3 spec. All are JSON.

GrillSearchRequest

{
  "query": "string (required)",
  "doc_filter": "string",
  "exclude_doc_ids": ["string"],
  "return_assets": false,
  "return_page_images": false,
  "min_relevance": 0.3,
  "max_tokens": 4000
}

GrillSearchInDocRequest

Same as GrillSearchRequest, except both query and doc_filter are required and doc_filter must be non-empty.

RetrievalContext

{
  "context": "string (XML+Markdown — see RetrievalContext format page)"
}

DocInfo

{
  "doc_id": "string (required)",
  "title": "string",
  "language": "string",
  "filename": "string",
  "pages": 0,
  "chunkset_count": 0,
  "chunk_count": 0,
  "image_count": 0,
  "table_count": 0,
  "ingested_at": "RFC 3339 timestamp",
  "source_job_id": "uuid"
}

ListDocsResponse

{
  "namespace": "string",
  "total_documents": 0,
  "documents": [ /* DocInfo */ ]
}

DeleteDocResponse

{
  "doc_id": "string",
  "vectors_deleted": 0,
  "storage_deleted": true
}

PublicJob (for /grill/ingest)

{
  "job_id": "uuid",
  "created_at": "RFC 3339 timestamp",
  "status": { "job_id": "…", "status": "pending|processing|done|failed", "code": 200 },
  "properties": { "file": { "filename": "string", "size": 0 }, "base_url": "string" }
}

See also

• Authentication
• Quickstart
• RetrievalContext format
• API v3 Swagger