Documentation
An overview of the HCX customer API. Access is by invitation during the private beta.
This page describes the shape of the API, not a commitment about availability, pricing or performance. Details can change before general release.
Authentication
Requests carry an API key issued by HCX in an Authorization: Bearer header. Keys belong to one customer account, can be created and revoked by that account, and should be kept secret.
Resources
| Purpose | Request |
|---|---|
| Your account | GET /v1/me |
| List what you can run | GET /v1/catalogue |
| Register an input file (upload, then complete) | POST /v1/uploads, POST /v1/uploads/{id}/complete |
| Register an input held at your own location | POST /v1/sources/origin |
| Describe a batch | POST /v1/manifests |
| Get a quote for a batch | POST /v1/quotes, GET /v1/quotes/{id} |
| Submit a batch | POST /v1/batches |
| Follow a batch | GET /v1/batches, GET /v1/batches/{id}, GET /v1/batches/{id}/items |
| Verification record | GET /v1/batches/{id}/verification |
| Results | GET /v1/batches/{id}/results |
| Cancel a batch | POST /v1/batches/{id}/cancel |
| Invoices and statements | GET /v1/invoices, GET /v1/statement |
| Manage API keys | GET, POST, DELETE /v1/api-keys |
| Completion notifications | GET, POST, DELETE /v1/webhooks |
Conventions
- JSON request and response bodies, over HTTPS only.
- Idempotency. Submitting a batch requires an
Idempotency-Keyheader, so a retried request never creates a second batch. - Quotes first. A batch is submitted against a quote, which fixes what will be run and the terms it will be billed on.
- Asynchronous. Batches complete in the background. Poll the batch, or register a webhook.
- Provenance. Results come with a verification record describing how each part was produced and checked.
- Errors use standard HTTP status codes and return a JSON body with a human-readable message.
Terms of use
Use of the API is subject to the Terms and the Acceptable use policy. Rate cards, completion windows and service levels are agreed with each customer and are not published here.
Questions or access requests: [email protected].