Perception
Ground claims
- Body: the document service's request for this operation. Ground lists its options and result.
- `source`: a url, a parse_result of one of your own jobs, or a workspace_file you uploaded. Upload one with POST /v1/documents/upload-grants.
- Billing: admitted only with reserved free/prepaid credit or explicitly enabled pay-as-you-go. Execution stops at its funded limit. Final credits are charged once after successful completion. A job that fails or is cancelled before completion is not charged.
- Retries: the same Idempotency-Key with the same body returns the same job. With a different body, it answers 409.
- Body: the document service's request for this operation. Ground lists its options and result.
source: aurl, aparse_resultof one of your own jobs, or aworkspace_fileyou uploaded. Upload one withPOST /v1/documents/upload-grants.- Billing: admitted only with reserved free/prepaid credit or explicitly enabled pay-as-you-go. Execution stops at its funded limit. Final credits are charged once after successful completion. A job that fails or is cancelled before completion is not charged.
- Retries: the same
Idempotency-Keywith the same body returns the same job. With a different body, it answers409.
Other errors (413, 500, 502, 503, 504, 529) are on Errors.
Authorization
bearerAuth Your API key, sent as Authorization: Bearer nace_sk_...
- Where: the dashboard's API Keys page. It is shown once, when you create it.
- Format:
nace_sk_followed by 43 URL-safe characters (A-Z,a-z,0-9,_and-). - Limit: an account can hold at most 3 active keys.
- Wrong or missing key: returns
401 authentication_error.
In: header
Query Parameters
Hold the request open until the job finishes, up to this many seconds. 0 (default) returns at once; a value above 60 waits 60.
0 <= valueHeader Parameters
Up to 200 characters, unique per account. Retry with the same key and body to get the same job instead of a second one.
length <= 200Request Body
application/json
targets is the text to find in the source. Each target is resolved to its locations in the document.
Workspace files the run can see besides source.
items <= 50Show child attributes
Optional display name for the run.
Show variants
Match caps, semantic score floor, and whether to mint crop preview URLs.
Show child attributes
Caller-minted grouping id; jobs submitted together share it. Not a server-side resource.
Show variants
One of three kinds:
- A URL:
{"type":"url","url":"https://...","file_name":"a.pdf"} - A parse of one of your jobs:
{"type":"parse_result","job_id":"..."} - A workspace file:
{"type":"workspace_file","workspace_id":"...","file_id":"..."}
Quoted strings to locate, up to 30. Exactly one of claims or targets must be set.
Show variants
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/documents/ground" \ -H "Content-Type: application/json" \ -d '{ "source": { "type": "url", "url": "https://console.nace.ai/samples/wm-recycle-america-invoice-iac3353061-2022-08-15.pdf", "file_name": "invoice.pdf" }, "targets": [ { "id": "total", "text": "Total" }, { "id": "supplier", "text": "WM Recycle America", "hint": "The company that issued the invoice" } ] }'{ "job_id": "453bd7d7-5355-4d6d-a38e-d9e7eb218c3f", "kind": "parse", "status": "queued", "result": null, "credits": 0, "usage_final": true, "created_at": "2019-08-24T14:15:22Z", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "timing": { "received_at": "2019-08-24T14:15:22Z", "observed_at": "2019-08-24T14:15:22Z", "completed_at": "2019-08-24T14:15:22Z", "elapsed_ms": 0, "total_ms": 0, "first_response_ms": 0, "breakdown": { "preparation_ms": 0, "queue_ms": 0, "ndi_processing_ms": 0, "result_preparation_ms": 0, "delivery_wait_ms": 0, "document_finalization_ms": 0 } }, "cost": { "pricing_version": "string", "total_usd": "string", "lines": [ { "operation": "parse", "quantity": 0, "unit": "page", "execution": "fresh", "unit_price_usd": "string", "amount_usd": "string", "reuse_reason": "string" } ] }}