Developers
A small HTTP surface, described exactly
Baton has two HTTP endpoints today, and they authenticate with your session rather than with an API key. That is a deliberate description of a real state of affairs, not a preview of one.
Read this first
What does not exist yet
No API keys
No webhooks
No SDKs, no OpenAPI spec
If an API is what you need from Baton, it is on the Impact roadmap rather than in the product, listed there as not yet built, alongside webhooks and embedded signing, so you can see exactly where it stands before you plan around it.
Reference
The endpoints that do exist
Both live under /api/v1, both require an active session in an organization, and both are authorized against your role in exactly the same way the application screens are, so there is no privileged API path around the permission layer.
POST/api/v1/documents/upload
Create a document from a PDF. multipart/form-data with a file part, plus optional title and a comma-separated tags field. Returns 201 with the new document.
The body is rejected from the Content-Length header before a byte is read if it is over the 25 MB limit. Uploading counts against your organization’s hourly upload and byte limits.
GET/api/v1/documents/{id}/file
Serve a document’s bytes. ?kind= selects the version, the current one by default, and ?download=1 asks for an attachment disposition, which additionally requires download permission.
Bytes are proxied through the application rather than handed out as a pre-signed storage URL, on purpose: a pre-signed URL is a capability that escapes both authorization and the audit trail. Every read is written to the chain before any bytes leave, so an unaudited disclosure cannot happen: if the write fails, the read does not.
Errors
Failures are RFC 9457 problem details, not bare strings, and the message is written to be shown to a person rather than only logged. A rejected PDF is a 422 with a specific reason, never a 500.
{
"type": "about:blank",
"title": "That file cannot be used",
"detail": "This PDF is encrypted, so its pages cannot be read.",
"status": 422,
"code": "encrypted"
}The status codes you should expect: 201 created, 400 malformed request, 401 no session, 403 not permitted for your role, 404 no such document (also returned instead of 403 where existence itself should not be confirmed), 413 too large, 422 unusable PDF, and 429 rate limited with a Retry-After header.
Rate limits
Limits are per organization and per window, aligned to the clock rather than to first use, so two servers checking the same limit at the same moment agree. A refusal carries Retry-After in seconds, always at least 1. A Retry-After: 0 invites the retry a rate limit is asking you not to make. The numbers are on the pricing page.
Idempotency
Not implemented. When the public API ships, every state-changing POST will accept an Idempotency-Key header; today a retried upload creates a second document. Worth knowing before you write a retry loop.
Stability
The /api/v1 prefix is a statement of intent rather than a commitment we have earned yet. Until API keys exist there is no supported integration to break, so treat these two endpoints as internal and expect the published surface to be announced rather than discovered.
Reporting a security issue
Tell us before you tell anybody else, at the security address in the terms, and we will not come after you for looking. Testing against your own organization’s data is fine; attempting to reach another organization’s is not, and the database will refuse you anyway.