API reference · Revern

Overview

Two endpoints over HTTPS. Send a photograph, get back where it was taken or what vehicle is in it, with the evidence for the answer. Every call is metered against the credit balance on your Revern account.

Both are synchronous: the connection stays open until the run finishes, which typically takes between twenty seconds and three minutes. That is deliberate rather than a limitation. A job you poll has to be held somewhere until it is collected, and we would rather have nowhere to hold it. Set a client timeout of five minutes.

Base URL

https://revern-server.onrender.com

A first call

curl -X POST https://revern-server.onrender.com/v1/locate \
  -H "Authorization: Bearer $REVERN_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d "{\"version\":1,\"sceneCropBase64\":\"$(base64 -i photo.jpg)\"}"

Authentication

A bearer token on every request. Create a key in the console under Settings, API. It is shown once and stored only as a SHA-256 hash, so it cannot be recovered: if it is lost, revoke it and create another.

Header

Authorization: Bearer rv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rules

Personal plan or above. Free accounts cannot hold a key, and an existing key stops working the moment a paid plan lapses. The plan is checked on every call, not when the key was created.
Server-side only. Cross-origin requests from browsers are not permitted. A key in front-end code is a key anybody can read and bill against.
Six keys per account. Enough for development, staging and production with room to rotate one before deleting the old one. Revoking takes effect within a minute.
Keys are per operator. A key spends the credits of the account that created it. Credits are never shared across an organisation, on any plan.

Pricing

10 credits per minute of agent time, rounded to the nearest minute with a one-minute minimum, taken from the same balance the console spends. Identical to what the product charges itself, so the API can never quietly be the expensive door.

A run that the agent completes is charged, including one that honestly refuses: working the frame and reporting that it does not support a claim is the product working. A run that fails with a 502 is not charged. Every response carries creditsCharged, so reconciliation is a field rather than an invoice you have to model.

The Personal plan is $29 a month and includes 2,500 credits, which is about four hours of agent time.

Endpoints

POST/v1/locate30 to 180 seconds

Returns ranked candidate regions for where a photograph was taken, each with a radius it can defend and the evidence behind it.

Example

curl -X POST https://revern-server.onrender.com/v1/locate \
  -H "Authorization: Bearer $REVERN_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d "{
    \"version\": 1,
    \"sceneCropBase64\": \"$(base64 -i photo.jpg)\"
  }"

Request body

version: Always 1. Present so a future shape can be added without breaking yours.
sceneCropBase64: The photograph, base64, no data URL prefix. Send the full frame rather than a crop: the agent zooms into regions itself, and anything removed here is detail it can never recover.
supportingImages: Up to 5 further frames of the same place. A second angle is often the difference between a street like this and this street. Context for the first image, not separate searches.
takenAt: ISO capture time, if you have it. Constrains sun angle and shadow reasoning.
camera: Camera make and model. Occasionally narrows region or era.
scopeCountry: ISO 3166-1 alpha-2, to restrict the search to one country.
scopeArea: A named area to restrict the search to, 2 to 200 characters.
mode: Fast trades depth for time, and costs less because it runs for less time.

Response

resultId: This run. Not stored; yours to keep or discard.
candidates: Ranked. Each carries coordinate, radiusMeters, tier, an optional name, locality, region and country, and the evidence that produced it.
candidates[].tier: The confidence band. Radius floors: 60 m for exact, 400 m for nearby, 8 km for area. A claim tighter than 250 m is only made with independent support.
candidates[].evidence: Every signal that moved the answer, each with a kind, a source and a weight. This is what makes a result arguable rather than merely produced.
notes: The agent’s reasoning, in order.
refused: Set when nothing in the frame pins it to a verifiable place. A refusal is a real answer and is charged, because the work was done.
creditsCharged: What this call cost your balance.

POST/v1/car20 to 90 seconds

Returns ranked make, model and production-year candidates for a vehicle in frame, from bodywork and lamp signature.

Example

curl -X POST https://revern-server.onrender.com/v1/car \
  -H "Authorization: Bearer $REVERN_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 180 \
  -d "{
    \"version\": 1,
    \"imageBase64\": \"$(base64 -i car.jpg)\"
  }"

Request body

version: Always 1.
imageBase64: The photograph, base64, without a data URL prefix. JPEG, PNG, WebP or HEIC. Up to 8,000,000 characters of base64, which is about 6 MB of image.
supportingImages: Up to 5 further frames of the same vehicle.
region: Optional. Fractions of the frame, each 0 to 1, to point at one vehicle in a photograph containing several.

Response

resultId: This run.
candidates: Ranked make, model and year range, each scored, with the distinguishing features that separated it from the next one.
summary: What was read off the frame, in a sentence.
refused: Set when the frame does not support an identification.
creditsCharged: What this call cost your balance.

Errors

Every failure is an HTTP status and a single error string. There is no error-code taxonomy to learn, because six outcomes do not need one.

400: Invalid request body.; A field is missing, the wrong type, or an image exceeds 8,000,000 base64 characters. Check the shape above; the most common cause by far is an oversized image.
401: Invalid API key.; The key is malformed, unknown or revoked. These are one answer on purpose. Create a new key in the console.
402: Out of credits.; The account has no balance left. Nothing was charged and no work was done.
403: No API access on this plan.; The key is valid but the account is on the free plan, or a paid plan has lapsed. The API needs Personal or above.
429: Too many requests.; Back off and retry after the `retry-after` header.
502: The run failed.; A provider or the agent failed. Nothing is charged for a failed run. Safe to retry.

Limits

Image size: 8,000,000 characters of base64 per image, which is about 6 MB of bytes. Over this the whole request is rejected with a 400 and no indication of which field was at fault, so check it before sending.
Image dimensions: No hard limit, but nothing beyond 2,576 pixels on the long edge is read. Downscale before encoding: it is faster to upload and costs you nothing in accuracy.
Supporting images: Up to 5, and they are context for the first image rather than separate searches. A second angle on the same corner is often the difference between a street like this and this street.
Requests per minute: Rate limited per client address. Exceeding it returns 429 with a retry-after header. If you need a higher ceiling, ask.
Formats: JPEG, PNG and WebP. Send base64 with no data URL prefix.

Data handling

The reason the API is synchronous rather than a job you poll. Each of these is a constraint in the code that serves the request, not an undertaking in a policy document.

Images are never stored: The photograph exists in the memory of the request that carried it and is released with it. It is never written to disk, never put in object storage, and never used for training.
Results are never stored: Coordinates, radii, evidence and notes are returned to you and kept nowhere. There is no job to poll and no history to read back, which is the reason the API is synchronous.
Only counts are logged: What is recorded is the endpoint, the status, the duration, the token counts and the credits charged. No image, no coordinate, no text read off a frame.
No faces, no plates: Faces and body features are excluded from location reasoning entirely, and numberplates are never read. There is no facial recognition in this API to disclose.

Keys are managed at app.revern.io/settings/api.