You keep
Your framework, host, sign-in and database.
Documentation
API v1Genaro is the generative-media piece of your app. You keep your own framework, host, sign-in and database. Genaro runs the models, keeps each user's library and finishes the long jobs.
You keep
Your framework, host, sign-in and database.
Genaro runs
The models, each user's library and the long jobs.
Your server routes call
https://api.genaro.ai/api/v1
The API contract and developer environment are live. Stripe accepts test payments only, and Genaro is not yet cleared for real customer funds or production media. Complete the launch gates before using this service for production workloads.
Quickstart
Set me up with Genaro: https://genaro.ai/start
Paste it into Claude, Cursor or ChatGPT. Your agent signs you up and you approve once.
Or point any MCP client at https://genaro.ai/mcp: it opens your browser to sign in, with no key to paste.
Keep the Workspace key out of browser and mobile code. Subscribe an HTTPS endpoint to generation lifecycle events, then read the completed Generation to retrieve its output Assets or error.
01 · Concepts
Ownership map
One Account funds one or more isolated Workspaces.
Owns its Generations, Assets, webhook endpoints, and usage.
user_2abc123
Their Generations, Assets, and usage
user_7def456
Another user's library
Has its own resources and users. Its key receives 404 for Workspace A IDs.
Genaro owns
Workspace isolation, durable operations and Assets, provider dispatch, signed webhook events, usage attribution, and prepaid charging.
Your application owns
Users, permissions, review and editorial decisions, customer experience, and any billing of your downstream users.
user_id, org_id, and project_id
say whose a resource is.
All three are optional. Send the IDs your app already has, such as Clerk's
user_…
and org_…: for example
"user_id": "user_2abc123", "org_id": "org_3xyz", "project_id": "project-7"
on a Generation or Asset. Genaro returns them on those resources, webhook events, and usage records, and every list filters by the same names: ?user_id=user_2abc123&project_id=project-7.
metadata
is yours alone: Genaro stores it and returns it unchanged, and never indexes or filters by it. The Workspace API key still controls access; none of these fields grants permission.
02 · Your users
Pass your sign-in provider's user ID with each generation and upload. Genaro keeps what each user makes together, so your app can list it back.
Step 1 · Request
POST /api/v1/generations
{
"model": "krea-2",
"user_id": "user_2abc123",
"org_id": "org_3xyz",
"project_id": "project-7",
"params": {"prompt": "Studio portrait, soft window light"}
}
Use the IDs your sign-in provider already gives you, such as Clerk's
user_…
and org_…. Every Asset a generation makes carries its user_id, org_id, and project_id. Uploads (POST /assets), groups, and training take the same three fields.
Step 2 and 3 · Requests
GET /assets?user_id=user_2abc123&status=ready
GET /generations?user_id=user_2abc123
GET /usage/summary?user_id=user_2abc123
GET /generations?org_id=org_3xyz&project_id=project-7
Filters combine with AND. Lists are newest first and page with next_cursor.
GET /users
lists every user_id
with its Asset count, and DELETE /users/{user_id}
removes one user's Assets and groups when they delete their account.
user_id
keeps users' files apart; it is not a permission. Your one key can read every user's library, so your app's server routes take the user ID from the signed-in session and only then call Genaro. See
Request fields
for the limits on these fields and metadata.
03 · First generation
Create and fund an Account, create a Workspace key, then run these requests from your server. The plaintext key is shown once.
Step 1 · Request
curl https://api.genaro.ai/api/v1/models \
-H "Authorization: Bearer gn_live_REPLACE_ME"
Step 1 · 200 OK · selected fields
{
"object": "list",
"data": [{
"id": "krea-2",
"name": "KREA 2",
"type": "image",
"capabilities": ["text_to_image"],
"availability": "preview",
"parameters": {
"prompt": {"type": "string", "required": true},
"aspect_ratio": {"type": "enum", "default": "4:5"},
"resolution": {"type": "enum", "default": "2k"}
}
}]
}
available
or preview.
The model list can include models that are visible but do not accept generation requests yet. Read
GET /models/krea-2
for the complete parameter schema before building the request body.
Step 3 · Request
curl https://api.genaro.ai/api/v1/generations \
-H "Authorization: Bearer gn_live_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{
"model": "krea-2",
"user_id": "user_2abc123",
"org_id": "org_3xyz",
"project_id": "project-7",
"params": {
"prompt": "A copper robot in a daylight studio",
"aspect_ratio": "4:5",
"resolution": "2k"
},
"metadata": {"scene_id": "opening_title"}
}'
Immediate response · 202 Accepted · selected fields
{
"id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
"object": "generation",
"status": "pending",
"model": "krea-2",
"user_id": "user_2abc123",
"org_id": "org_3xyz",
"project_id": "project-7",
"metadata": {"scene_id": "opening_title"},
"price": {"value": "0.065400", "currency": "usd"},
"assets": [],
"error": null,
"accepted_at": "2026-08-17T18:42:05Z",
"created_at": "2026-08-17T18:42:05Z"
}
Terminal response · 200 OK · selected fields
{
"id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
"object": "generation",
"status": "succeeded",
"model": "krea-2",
"price": {"value": "0.065400", "currency": "usd"},
"assets": [{
"id": "0190d9c1-46ba-78be-8123-6d40462e26bd",
"object": "asset",
"status": "ready",
"media_kind": "image",
"mime_type": "image/png"
}],
"error": null,
"finished_at": "2026-08-17T18:42:41Z"
}
Status check
GET /generations/0190d9b8-...
After a completion webhook, read the generation to retrieve its full Asset or error details.
Download
GET /assets/0190d9c1-.../download
The response contains a short-lived download URL. Treat that URL as a secret capability.
04 · Assets
A URL is read for one generation. An Asset is a durable, Workspace-scoped media resource that can be reused and downloaded later.
Use asset_id when
"image": {"asset_id": "0190..."}
Use url when
"image": {"url": "https://..."}
Direct upload sequence
POST /assets
Receive the pending Asset and short-lived PUT URL.
PUT signed_url
Upload bytes directly to object storage.
POST /assets/:id/complete
Genaro verifies the object and marks it ready.
asset_id or /download
Reference it in work or request a short-lived GET URL.
Ready means usable.
A generation input must reference a ready
Asset of the correct media kind in the same Workspace. A temporary URL input does not create an Asset. Keep upload and download URLs out of logs because possession grants temporary access.
Workflows
An App is a durable workflow you write in TypeScript with
@genaro/apps-sdk
and publish to a Workspace. A run's generations and text model calls go through the
same pipelines as the API key that started it; the run suspends while a generation
or a person's review is pending and resumes when it is ready.
The Apps guide explains how to write, test, publish and run one, with every
ctx
action and review type. Its plain-text twin is written for coding agents.
Publishing needs content:write; starting runs and answering review
steps needs generate; reading Apps, runs, traces and reviews needs read. The key's model allow-list and spend cap govern every
generation and text model call a run makes, and revoking the key stops the run.
| Operation | REST (/api/v1) |
MCP tool |
|---|---|---|
| List and get Apps |
GET /apps
GET /apps/{app_id}
|
genaro_list_appsgenaro_get_app
|
| Publish from TypeScript source or a bundle |
POST /apps
|
genaro_publish_app
|
| Archive an App |
POST /apps/{app_id}/archive
|
genaro_archive_app
|
| Start a run |
POST /apps/{app_id}/runs
|
genaro_create_app_run
|
| List and get runs |
GET /app_runs
GET /app_runs/{app_run_id}
|
genaro_list_app_runsgenaro_get_app_run
|
| Read a run's execution trace |
GET /app_runs/{app_run_id}/trace
|
genaro_get_app_run_trace
|
| List and get review steps |
GET /app_reviews
GET /app_reviews/{app_review_id}
|
genaro_list_app_reviewsgenaro_get_app_review
|
| Answer a review step |
POST /app_reviews/{app_review_id}/resolve
|
genaro_resolve_app_review
|
Classification
POST /judgments
asks TypeSafe's Jev typed questions about text and images: is the face visible,
which reference does this take match, where is the logo. Jev never writes text; it
returns probabilities your code thresholds. Models are the
type: judgment
entries of GET /models, pinned versions such as jev-1.14.0.
| Type | Asks | Answers |
|---|---|---|
noul |
A yes/no question; optional criteria define true and false.
|
noul, the probability of yes |
choice |
One option of criteria, an object of option names to descriptions or example images.
|
choice, confidence, probabilities
|
score |
A level on criteria, an ordered array of 1 to 10 levels.
|
score, confidence, legend,
probabilities
|
box |
Where one thing is in an image (Jev 1.14). Pair it with a noul: there is no "not found".
|
box: top, bottom, left,
right
as fractions
|
One yes/no question about an Asset
POST /api/v1/judgments
{
"model": "jev-1.14.0",
"state": {"photo": "listing"},
"images": {"listing": {"asset_id": "6f1c..."}},
"questions": {
"shows_face": {
"type": "noul",
"instructions": "Is a person's face clearly visible in `photo`?"
}
}
}
→ "answers": {"shows_face": {"type": "noul", "noul": 0.97}}
A Choice whose options are example images
{
"model": "jev-1.14.0",
"state": {"take": "take"},
"images": {
"take": {"asset_id": "2b0e..."},
"warm_ref": {"asset_id": "9d4a..."},
"cold_ref": {"data_base64": "iVBORw0KGgo...", "format": "png"}
},
"questions": {
"lighting": {
"type": "choice",
"instructions": "Which reference is the lighting of `take` closest to?",
"criteria": {
"warm_studio": "warm_ref",
"cold_daylight": "cold_ref",
"neither": "Matches neither reference."
}
}
}
}
Each key of images
is your own reference, written wherever the image goes in state,
instructions
or criteria
(never an object key); every one must be used. An image is a ready Asset
(asset_id) or inline base64. Genaro rotates it upright, converts WebP, GIF
and AVIF to JPEG, and resizes it so each side is 280 to 1568 pixels. Put an image
several questions use in state
once.
A judgment is charged the input tokens it used, images included, at the model's
per-million-token price, rounded up to $0.0001; output is free. It is held at, and
never charged more than, max_charge. A refused or failed judgment is not
charged. Needs the generate
scope; over MCP it is genaro_create_judgment.
Moderation
POST /safety/checks
screens your own content and reports a verdict per category with evidence. Genaro
never blocks anything: you decide what to do with a flagged result. The
prompt
check reads a generation prompt and its negative prompt with a word
filter and TypeSafe's Jev; adult sexual content on its own is never flagged. The image checks nudity,
sexual_act
and violence
read one image on Genaro's own servers, and jev_image
asks TypeSafe's Jev about the same image as a fast, cheap second opinion.
famous_person
asks, on Genaro's own servers, whether a face belongs to one of about 93,000 famous
people, and openai_moderation
adds OpenAI's free moderation model on the prompt and the image. Where
several sources report the same category, combined
gives one verdict and shows where they disagree.
| Source | Categories | Reports |
|---|---|---|
word_filter |
blocked_term, minor_age, minor_abuse, minor_sexualized, minor_depicted, negative_prompt_signal; bestiality, creature, non_consent,
torture
alongside sexual content
|
evidence: the matched terms and where they are in your text
|
jev |
minor, evasion; non_consent, bestiality, creature, incest, step_family,
gore
together with sexual content
|
score, the probability of yes |
nudity |
neutral, low, medium, high
(Freepik's nsfw_image_detector)
|
level
and a score per level, flagged at and above flag_level
|
shieldstral |
sexual_act; gore
and weapons
for violence
(Shieldstral-1.0-3B)
|
score, the probability of yes, flagged at and above
threshold
|
jev on an image |
nudity, gore
(blood or injury) and weapons
for jev_image; person
and lettering
(text or a watermark) as facts, never flagged. Never asked about age.
|
score, the probability of yes, flagged at and above threshold. A preview from TypeSafe, not production-grade
|
arcface_r50 |
famous_person: every face, matched against about 93,000 famous
people
|
Per face matched
and the closest person's name, Wikidata id, score and own threshold
|
openai |
openai_moderation
on the prompt: sexual, minor_sexualized, harassment, hate, illicit, self_harm, violence,
gore
and their variants; on the image only sexual, self_harm,
violence
and gore
|
Per category its input, OpenAI's score
and name, flagged at OpenAI's own thresholds
|
Screen a prompt
POST /api/v1/safety/checks
{
"checks": ["prompt"],
"prompt": "h4z4l. a woman reading in a cafe",
"negative_prompt": "blurry, child, teen",
"options": {"prompt": {"names": ["h4z4l"]}}
}
→ "flagged": false,
"checks": [{"check": "prompt", "categories": [
{"category": "minor_depicted", "flagged": false,
"source": "word_filter"},
{"category": "minor", "flagged": false,
"score": 0.02, "source": "jev"}, ...]}]
POST /api/v1/safety/checks
{
"checks": ["nudity", "violence"],
"image": {"asset_id": "5b7f0f8e-..."}
}
→ "checks": [
{"check": "nudity", "level": "low", "flagged": false,
"scores": {"neutral": 0.31, "low": 0.66,
"medium": 0.12, "high": 0.02}, ...},
{"check": "violence", "flagged": false, "categories": [
{"category": "gore", "score": 0.01, ...},
{"category": "weapons", "score": 0.03, ...}]}]
options.prompt.names
lists your LoRA trigger words and character names, read as "the woman" or "the
man" so a name never looks like leetspeak or a real person.
creatures: true
also flags monsters and aliens in sexual content. The image checks read
image
as an asset_id, a url
on a public HTTPS host, or data_base64.
options.nudity.flag_level
(default medium) and options.violence.threshold
(default 0.5) set when they flag, as do
options.sexual_act.threshold
and options.jev_image.threshold. Video and minor
are not available yet and are refused with a 422, as
is any unknown check.
famous_person
reports each face's box, whether it matched, and its closest
famous person: name, Wikidata id, score and that person's own threshold.
It runs on Genaro's own servers, and the image never leaves Genaro. Images
may be at most 10 MB and 40 megapixels. A few checks run at once; when every
slot is busy, or the check is down, its result says status: "busy"
(retry after error.retry_after
seconds) or "unavailable", it isn't charged, and the other checks
still run.
openai_moderation
is free and runs only alongside another check. It reads the prompt and the
image apart, so their findings never mix; graphic violence joins
gore
and, on the prompt, sexual content with minors joins
minor_sexualized
in the combined verdict. On an image it can't spot an apparent minor. Your
prompt and image are sent to OpenAI; never send known or suspected child
sexual abuse material. When OpenAI is rate-limiting or down its result says
status: "busy"
or "unavailable"
and the other checks still run.
When sources report the same category of the same input, such as nudity from
Freepik and from Jev, combined.categories
lists each source's own result, whether they disagree, and one
verdict under combine: any
(the default) flags it when any source does, majority
when more than half do, all
when every source does. Disagreement is the signal worth a person's look. The
top-level flagged
and every check's own result are unchanged.
About $0.07 per 1,000 prompt checks, often less: the Jev input tokens each check
uses, never more than its max_charge. The word filter is free, and
when Jev fails you get the word filter's verdict and pay nothing. Image checks
are a fixed price each: about $0.04 per 1,000 images for nudity, about $0.45
per 1,000 for sexual act and violence together. jev_image
is charged per Jev input token like the prompt check, about $0.10 to $0.25 per
1,000 images depending on size. famous_person
is about $0.56 per 1,000 images, and openai_moderation
is free. An image check that is at capacity or down says busy
or unavailable
in its result, the other checks run, and it costs nothing.
GET /safety/check_types
lists the checks and their price. Needs the generate
scope; over MCP it is genaro_create_safety_check.
05 · Platform model
Generation request
Genaro records the request, charges its quoted price, and starts one Generation.
Execution plane
Trace-resource associations record which data participated in the transaction.
Content plane
derived_fromsource Asset → derived Asset
Execution concepts
The complete record of one Generation. It begins when Genaro accepts the request and follows the work through completion.
One timed operation inside a Trace, such as provider execution, analysis, or media transformation.
The requested creative outcome: resolved prompt, media inputs, model contract, parameters, output count, and accepted price.
One concrete attempt through a model release and provider. A retry creates another Run without changing the original Intent.
Content concepts
The durable identity of an image, video, or audio item. Storage locations and delivery formats can change without changing the Asset.
An immutable technical form of an Asset, such as the original, an optimized AVIF, a compatibility JPEG, a poster frame, or a video proxy. A format change creates a Rendition; a semantic content change creates a new Asset.
derived_from
A direct, typed Asset-to-Asset link showing that source media contributed to derived media: a
reference
for each Generation input, or a kind you set yourself (edit, upscale, frame, …). Multiple inputs and outputs create multiple simple links, preserving clear ancestry.
v1, v2, v3 of one thing: Assets sharing a version family, exactly one of them current. List with
current_versions_only=true
to see each family once.
A typed, ordered or unordered collection for candidates, sequences, albums, or reference sets. Membership organizes Assets; it does not imply lineage.
Associates a Trace or Span with a resource as an input, output, subject, observation, or update. Typed relationships and lineage remain distinct.
Application data · 01
A generation may finish after the original request has left your server. When its webhook arrives, your application still needs to know which scene or draft requested it. Store that context with the Generation instead of reconstructing the connection later. Users, orgs, and projects have their own fields, user_id, org_id, and project_id, which lists can filter by.
A generation for one scene
{
"project_id": "project-7",
"metadata": {
"scene_id": "opening_title",
"draft": 3
}
}
Metadata is an optional JSON object that Genaro stores and returns with a resource, unchanged. Genaro never reads, indexes, or filters by it.
Application data · 02
A captioning model, a safety classifier, and a human editor may all add information to the same image. If they share one Metadata object, unrelated systems have to edit the same JSON and newer results can erase the work that came before them.
Three annotations on one Asset
[
{
"type": "caption",
"data": {
"text": "Cyclist on a wet city street"
}
},
{
"type": "safety",
"data": {
"classification": "safe"
}
},
{
"type": "editor_note",
"data": {
"text": "Use the tighter crop"
}
}
]
An Annotation is a separate record attached to an Asset. One Asset can have many Annotations, so captions, scores, labels, regions, and notes from different systems and people do not overwrite one another. Each Annotation can keep its source and history without changing the Asset.
/assets/{asset_id}/annotations
Integration · 03
Generation is asynchronous. Your server should not keep the request open or repeatedly check for completion. Subscribe an HTTPS endpoint to the lifecycle changes your application cares about, then react when Genaro delivers them.
generation.succeeded
{
"object": "event",
"type": "generation.succeeded",
"operation_id": "0190d9b8-7d31…",
"occurred_at": "2026-08-17T18:42:41Z"
}
An Event records that a specific state change happened at a specific time. Read generation Events through the API or receive selected types through signed webhooks. A succeeded Event carries the run's output Asset id and a failed Event its error, so your application can act on the Event alone.
Operations · 04
A webhook tells your application that a Generation finished. Engineers may also want its queue time, run time, and final status in the observability system they already use.
One generation Trace
Trace: generation 0190d9… └─ Span: genaro.generation ├─ generation.accepted ├─ generation.running └─ generation.failed
OpenTelemetry is an industry standard for exporting operational telemetry. Register an OTLP/HTTP traces endpoint and Genaro will export a Span for each completed Generation, with its lifecycle changes recorded as Span events.
POST /telemetry_endpoints
Access control
One key resolves one Workspace and its parent Account. Request fields cannot override either boundary. Limit what a key can do with scopes and an optional model list.
| Scope | Allows |
|---|---|
read |
Reads and quotes |
generate |
Generations, chat, and agents |
content:write |
Changes to stored content |
keys |
Key and telemetry management; includes webhooks
|
webhooks |
Webhook endpoints and their deliveries; an agent may hold it when it asks |
Set allowed_models
to exact model IDs to limit generations, quotes, chat, and agent turns.
null
allows all models; an empty list allows none.
A key created with missing or empty permissions
keeps full access, so existing clients continue to work.
A key can create another key only with the same or narrower permissions and models.
A missing scope returns 403 with insufficient_scope; a forbidden model returns 403 with model_not_allowed. Create keys in the console or with POST /api/v1/api-keys.
06 · Request fields
Authentication, attribution, and application metadata serve different purposes.
| Value | Job | Scope | Do not use it for |
|---|---|---|---|
Workspace key |
Authentication and resource isolation | One Workspace | A downstream browser or mobile session |
user_id, org_id, project_id
|
Which of your users, orgs, and projects a resource belongs to; every list filters by the same names | Reusable inside one Workspace | Authorization, authentication, or a separate balance |
metadata |
Your own context, stored and returned unchanged | Stored on a resource | Filtering, trust decisions, or billing |
user_id, org_id, and project_id
are strings of at most 255 characters; anything else is a 422. metadata
must be a JSON object and accepts at most 32,000 encoded bytes per resource.
07 · Generations
A generation moves forward through managed work. Your request connection may end; the generation continues until a terminal state.
Validation, pricing at the quote, operation creation, debit, and accepted event commit together.
Genaro materializes output as a durable ready Asset and records successful usage.
Genaro records a stable error and fully refunds the accepted charge.
08 · Webhooks
Register an HTTPS endpoint and select the generation event types your application needs. Genaro sends each selected event to that endpoint.
Register an endpoint
curl https://api.genaro.ai/api/v1/webhook_endpoints \
-H "Authorization: Bearer gn_live_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{
"url": "https://app.example.com/webhooks/genaro",
"event_types": [
"generation.succeeded",
"generation.failed"
]
}'
201 Created · selected fields
{
"id": "0190da31-75b6-742d-93eb-4907d32d2c15",
"object": "webhook_endpoint",
"url": "https://app.example.com/webhooks/genaro",
"event_types": [
"generation.failed",
"generation.succeeded"
],
"status": "active",
"signing_secret": "whsec_..."
}
The signing secret is returned only when the endpoint is created or its secret is rotated. An empty
event_types
array subscribes the endpoint to every available type.
Verify every delivery
webhook-timestamp
values more than five minutes from the current time.
Signed HTTP POST
{
"id": "0190da43-ddc4-79f5-b78e-e011866a78cc",
"object": "event",
"type": "generation.succeeded",
"operation_id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
"user_id": "user_2abc123",
"org_id": "org_3xyz",
"project_id": "project-7",
"data": {
"id": "0190d9b8-7d31-7c0b-9aaa-4a0d0d2466ad",
"run_id": "0190d9b8-7d4e-7a21-8c3f-5b6e0f1a9d27",
"run_index": 0,
"status": "succeeded",
"model": "krea-2",
"price": {"currency": "usd", "value": "0.065400"},
"output": {
"asset_id": "0190d9c1-2f0a-7b44-9e8d-3c1a6b7e5f90",
"content_type": "image/png",
"size_bytes": 1843204,
"width": null,
"height": null,
"duration": null
}
},
"metadata": {"scene_id": "opening_title"},
"occurred_at": "2026-08-17T18:42:41Z"
}
Deliveries include webhook-id, webhook-timestamp, and webhook-signature. The signed content is
webhook-id.webhook-timestamp.raw_body
using HMAC-SHA256 and the endpoint secret.
generation.succeeded
adds data.output
with the run's output Asset: asset_id, content_type, size_bytes, width, height, and
duration
(seconds). Dimensions and duration are measured after the Asset is stored, so they are often
null
in the event; read the Asset when you need them. output
is null
for a run whose result is data rather than an Asset. generation.failed
adds data.error
with the run's code
and message, as the Generation returns them. Use
GET /generations/:generation_id
only for what the event does not carry.
Agents
Genaro's tools are an MCP server at https://api.genaro.ai/mcp. It speaks standard Streamable HTTP (protocol versions 2025-06-18 and 2025-03-26) with JSON responses, and uses the same Workspace API key as the REST API.
claude mcp add --transport http genaro https://api.genaro.ai/mcp \
--header "Authorization: Bearer $GENARO_API_KEY"
Send only Authorization, Content-Type: application/json, and an
Accept
that allows JSON. tools/list, genaro_list_models, and
genaro_quote_generation
are free; genaro_create_generation
bills like POST /generations. The key's scopes and model list apply to every tool call.
Apps have their own tools: genaro_publish_app, genaro_create_app_run, genaro_get_app_run,
genaro_resolve_app_review
and the rest listed under Apps.
Starting a run is free; its generations and text model calls bill as the run reaches them.
Clients that support MCP sign-in (Claude Code, the Claude apps, Cursor, ChatGPT) connect with no key: add
https://genaro.ai/mcp
(Claude Code: claude mcp add --transport http genaro https://genaro.ai/mcp). The client opens your browser, you sign in and approve once, choosing the workspace and a monthly spending cap, and the agent appears under Connected agents, where you can revoke it. Genaro is the OAuth 2.1 authorization server: authorization code with PKCE, clients identified by a Client ID Metadata Document or dynamic client registration.
Paste
Set me up with Genaro: https://genaro.ai/start
into your agent. It reads https://genaro.ai/auth.md, registers with your email, and shows you a link and a 6-digit code. You approve once in the browser, choosing the workspace and a monthly spending cap; the agent then collects a workspace API key and adds this MCP server itself. You can revoke it under Connected agents in the console. The flow follows WorkOS's auth.md protocol (v0.6.0,
service_auth
only), with discovery at /.well-known/oauth-protected-resource
and /.well-known/oauth-authorization-server; every 401 from the API and MCP carries WWW-Authenticate: Bearer resource_metadata="…".
09 · Billing
The parent Account holds the prepaid balance shared by its Workspaces. A Workspace key can read only that Workspace’s resources, successful usage, and attributed ledger entries.
Genaro charges the price returned with the accepted generation response. That is the most the generation costs: it can settle below it at completion, never above.
When a length held at its maximum is measured, or the provider that served the run reports a lower cost, the difference is refunded as a separate
refund
ledger entry. Successful work appears in /usage
with its user_id, org_id, and project_id.
Failed work does not create a successful usage record.
GET /usage
Returns the current shared Account prepaid balance plus successful usage attributed to this Workspace.
Money values are exact USD decimal strings with six fractional digits.
GET /balance_transactions
Returns immutable charges and refunds attributed to this Workspace. Account funding and sibling Workspace entries stay excluded.
10 · Errors
Error bodies use error.type, an optional human message, and optional details. Provider and database internals do not cross the public boundary.
{
"error": {
"type": "validation_error",
"details": [{
"field": "prompt",
"message": "must be at most 20000 encoded bytes"
}]
}
}
| Status | Typical meaning | Your action |
|---|---|---|
401 |
Missing, invalid, expired, or revoked key | Stop and repair credentials. |
403 |
account_blocked: the Account is blocked for non-payment. Every
route refuses the key; the error carries a resume_url.
|
Add funds at resume_url, then retry.
|
402 |
Insufficient funds, or account_past_due: reads and downloads
still work but new generations and agent turns are refused
|
Add funds, then submit the work. |
404 |
Unknown ID or ID owned by another Workspace | Check the ID and authenticated Workspace. |
422 |
Validation, model, or media-input error | Correct the request before submitting a new generation. |
Use the HTTP status and error.type
for program logic. Use the OpenAPI document for the wire-level response schema.
11 · Operations
Follow these practices when storing credentials, handling webhook events and media, and reconciling usage.
Keep Workspace keys on the server and out of client bundles, logs, and transcripts.
Separate environments with separate Workspaces when independent isolation is useful.
Persist every returned generation ID beside your own job or resource record.
Subscribe to generation.succeeded
and generation.failed, then handle both.
Verify webhook timestamps and signatures against the exact raw request body.
Use ready Assets for durable or reusable media; keep signed URLs out of logs.
Authorize your users in your application; user_id
only records which user a resource belongs to.
Handle 401, 402, 404, and 422 responses explicitly.
Monitor prepaid balance and reconcile usage and ledger entries by Workspace.
Pin integration tests to OpenAPI and the exact endpoint behavior you depend on.
12 · Reference
This endpoint index belongs to the integration path explained above. The OpenAPI 3.1 document remains the canonical source for request and response schemas.
/models
List discoverable logical models.
/models/{model_id}
Read one model and its current parameter schema.
/generations
List recent Workspace generations.
/generations
Validate, price, debit, and submit managed work.
/generations/{generation_id}
Read current state, price, errors, and output Assets.
/assets
List durable Workspace Assets.
/assets
Create a pending Asset and direct upload request.
/assets/{asset_id}
Read one Asset in the authenticated Workspace.
/assets/{asset_id}/complete
Verify the stored object and mark the Asset ready.
/assets/{asset_id}/download
Create short-lived direct download URLs, up to 24 hours with expires_in.
/groups
List typed Workspace Asset groups.
/groups
Create a Group with an optional initial Asset order.
/groups/{group_id}
Read one Group and its ordered Assets.
/groups/{group_id}
Change the type, name, or metadata without changing membership.
/groups/{group_id}/assets
Atomically replace the complete ordered Asset list.
/groups/{group_id}
Delete the Group while retaining every Asset.
/users
List every user_id in the Workspace with its Asset count.
/users/{user_id}
Read one user, including the progress of a deletion.
/users/{user_id}
Delete the user's Assets, groups, and stored objects in the background.
/apps
List the Workspace's active Apps.
/apps
Publish an App from TypeScript source or a built bundle as a new version.
/apps/{app_id}
Read one App by id or slug.
/apps/{app_id}/archive
Archive an App; runs in progress finish.
/apps/{app_id}/runs
Start a run with input the App's schema accepts.
/app_runs
List App runs, newest first.
/app_runs/{app_run_id}
Read a run's status, steps, logs, result, and pending review.
/app_runs/{app_run_id}/trace
Read the run's execution trace as a tree of spans.
/app_reviews
List review steps runs are waiting on or have finished.
/app_reviews/{app_review_id}
Read one review step.
/app_reviews/{app_review_id}/resolve
Answer a pending review step; the run resumes.
/agents
List Workspace Agents.
/agents
Create a conversational Agent definition.
/agents/{agent_id}
Read one Agent by UUID or key.
/agents/{agent_id}
Update any Agent field except the immutable key.
/agents/{agent_id}
Archive the Agent; existing Conversations stay readable.
/agent-tools
List builtin tools an Agent can be granted.
/conversations
List Conversations, optionally filtered by Agent.
/conversations
Create a Conversation bound to one Agent.
/conversations/{conversation_id}
Read one Conversation and its pending tool calls.
/conversations/{conversation_id}
Archive the Conversation; messages stay readable.
/conversations/{conversation_id}/messages
List the message transcript in ascending order.
/conversations/{conversation_id}/messages
Send a user message and run one agent turn, optionally streamed.
/conversations/{conversation_id}/tool-results
Answer pending client tool calls and resume the paused turn.
/webhook_event_types
List the available webhook event types.
/webhook_endpoints
List Workspace webhook endpoints.
/webhook_endpoints
Register an HTTPS destination and receive its signing secret.
/webhook_endpoints/{webhook_endpoint_id}
Read one Workspace webhook endpoint.
/webhook_endpoints/{webhook_endpoint_id}
Change the URL, event selection, description, or status.
/webhook_endpoints/{webhook_endpoint_id}
Delete a webhook endpoint.
/webhook_endpoints/{webhook_endpoint_id}/rotate_secret
Replace the endpoint signing secret.
/events
List durable generation lifecycle events.
/events/{event_id}
Read one lifecycle event.
/usage
Read successful usage and the shared prepaid balance.
/balance_transactions
List Workspace-attributed charges and refunds.
/assets/{asset_id}/annotations
List the independent results attached to an Asset.
/assets/{asset_id}/annotations
Attach a caption, score, label, region, or note.
/annotations/{annotation_id}
Read one Annotation.
/telemetry_endpoints
List Workspace OTLP/HTTP trace destinations.
/telemetry_endpoints
Register an OTLP/HTTP traces endpoint.
/telemetry_endpoints/{telemetry_endpoint_id}
Read one telemetry destination without secret header values.
/telemetry_endpoints/{telemetry_endpoint_id}
Change its destination, headers, service name, or status.
/telemetry_endpoints/{telemetry_endpoint_id}
Delete a telemetry destination.