Usage & health

Check your metered usage for the current billing period, and probe service health.

Usage

GET/usageBearer auth

Return billed-action counts by kind: all time and for the current period, with the pages and context tokens metered under each kind.

Status codes

200The usage breakdown.
401Missing or invalid API key.

curl https://api.getemboss.ai/usage \
  -H "Authorization: Bearer sk_..."

Response

{
  "owner": "6c47f7f5-f921-4698-910f-95dd7d81310b",
  "email": "you@example.com",
  "period": "2026-09",
  "total": { "create": 12, "with_context": 4, "standard_fill": 3, "verify": 2, "read": 1, "package": 0, "send_fax": 2, "utility": 4 },
  "period_counts": { "create": 3, "with_context": 1, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 1, "utility": 1 },
  "total_pages": { "create": 31, "with_context": 9, "standard_fill": 6, "verify": 4, "read": 2, "package": 0, "send_fax": 4, "utility": 8 },
  "period_pages": { "create": 7, "with_context": 2, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 2, "utility": 2 },
  "total_ctx_tokens": { "create": 0, "with_context": 18420, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 0, "utility": 0 },
  "period_ctx_tokens": { "create": 0, "with_context": 4110, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 0, "utility": 0 },
  "total_context_pages": { "create": 0, "with_context": 11, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 0, "utility": 0 },
  "period_context_pages": { "create": 0, "with_context": 3, "standard_fill": 0, "verify": 0, "read": 0, "package": 0, "send_fax": 0, "utility": 0 }
}

Quote

POST/forms/quoteBearer auth

Price every route for this document and say whether the free tier covers it. Free and stateless; it counts as one call toward the hourly rate limit. The sample shows the shape; the amounts follow the live price list.

Parameters

Name	In	Type	Required	Description
`file`	body	file (multipart)	yes	The flat PDF to price.
`context`	body	file (multipart, repeatable)	no	Optional. Zero or more supporting documents, priced as with-context input. Repeat the field to attach more than one.

Status codes

200The price and free-tier verdict for every route.
400Not a PDF.
401Missing or invalid API key.
413Too many pages or too much context.
422Missing required file. Also pdf_unsafe: the PDF's form fields are built in a way that could compromise the service. Refused before any price, charge or stored file; the problem document's detail is "Emboss does not process PDF files that could compromise the service." and its code is pdf_unsafe.

curl -X POST https://api.getemboss.ai/forms/quote \
  -H "Authorization: Bearer sk_..." \
  -F "file=@application.pdf" \
  -F "context=@customer.json"

Response

{
  "pages": 3,
  "context_pages": 1,
  "already_fillable": false,
  "effective": "2026-09-07",
  "billing": { "has_card": false, "exempt": false, "billing_url": "https://getemboss.ai/dashboard/billing" },
  "lines": {
    "create_form": { "cents": 5, "free": true,
      "kinds": { "create": { "covered": true, "reason": "within_allowance", "remaining": 4 } } },
    "create_and_fill_from_context": { "cents": 8, "free": false,
      "kinds": { "create": { "covered": true, "reason": "within_allowance", "remaining": 4 },
                 "with_context": { "covered": false, "reason": "allowance_used", "remaining": 0 } } },
    "fill_from_data": { "cents": 2, "free": true,
      "kinds": { "standard_fill": { "covered": true, "reason": "within_allowance", "remaining": 4 } } },
    "verify": { "cents": 1, "free": true,
      "kinds": { "verify": { "covered": true, "reason": "within_allowance", "remaining": 4 } } }
  }
}

Health

GET/healthNo auth

Liveness probe. No authentication required.

Status codes

200Service is healthy.

curl https://api.getemboss.ai/health

Response

{
  "status": "ok"
}