API v1

Bildy API

Integrate Bildy Notes memory, the writing tools and the MCP endpoints into your app or AI agent. All features available via simple REST API with JSON responses.

Quick Start

1Get an API key - Sign in and generate a key below.
2Add the header - Include Authorization: Bearer bld_YOUR_KEY in every request.
3Make requests - All endpoints return JSON with { "data": { ... } } on success.

Example: Generate a LinkedIn post

curl -X POST https://bildy.ai/api/v1/notes/upsert \
  -H "Authorization: Bearer bld_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "folder": "support-memory",
  "title": "Important Facts",
  "content": "The customer prefers invoices by email."
}'

Agent Entry Point

If an AI agent gets this docs URL, start with the compact manifest for the shortest workflow guidance. Use the OpenAPI spec when the agent needs the full machine-readable endpoint contract.

Open agent manifest Open OpenAPI spechttps://docs.bildy.ai/https://docs.bildy.ai/openapi.jsonhttps://bildy.ai/api-agent-manifest.jsonhttps://bildy.ai/openapi.json

API Key

Your API key authenticates all requests and ties usage to your credit balance. Keep it secret - treat it like a password.

Keys are shown only once at creation. Store each key in your own secret manager (or environment variables). If a key is lost, create a new one and revoke the old key.

Limits

Images: generate, edit or storyboards20 / min
Video: generate30 / hour
Video: edit120 / hour
Model lists, balance, jobs60 / min
Max request body6 MB
Inline images per request4, 5.0 MB total
One image fetched by URL8 MB

A base64 image is about a third bigger than the file it came from, so four 1 MB photos will not fit in one body. Pass imageUrls instead and we fetch them, which skips the body limit entirely.

A submit that times out on the way back may still have made the job and charged for it. Send an Idempotency-Key header with each submit and resend with the same key: you get the original job back and are not charged again. Polls can simply be retried.

Credit Costs

A top-up gives you 1,000 credits for one euro, so a credit price divided by a thousand is what you pay in euros. Images and video are priced per model, and every model list below carries its own figure.

Generate or edit an image8 to 250
One second of video50 to 400
One storyboard112 credits
Improve text10 credits
Read and write notesfree
List models, read your balance, manage keysfree

Purchase credits →

Error Handling

All errors return a consistent JSON structure:

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "code": "error_code"
  }
}

Status	Code	Meaning
400	bad_request	Missing or invalid fields
400	invalid_json_body	Malformed JSON request body
400	references_not_supported	The video model takes no reference pictures or storyboard
400	too_many_references	More reference pictures than the video model takes. The storyboard counts as one
400	frames_or_references	The video model takes a first frame or references, never both in one clip
400	seconds_fixed_with_references	Veo makes clips from references at 8 seconds only
415	unsupported_media_type	Content-Type must be application/json
401	unauthorized	Missing, invalid or revoked credential. The response carries a WWW-Authenticate header naming the sign-in flow.
402	insufficient_credits	Not enough credits
429	rate_limited	Too many requests - check Retry-After header
500	provider_config_error	Provider env config missing on server
500	auth_config_error	API key verification service misconfigured
502	upstream_service_error	Upstream provider request failed
502	response_parse_error	Provider output was not parseable JSON
502	response_format_error	Provider output had no JSON object
500	internal_error	Server error - retry after a moment

Endpoints

Authentication

Images & Video

MCP Tools

Notes Memory

Writing

AI Agent Integration

The Bildy API works best for agents when they follow one simple rule: discover first, then act.

Golden Rules

→Use /api/v1 endpoints for REST workflows or /api/mcp endpoints for MCP clients.

→Treat all resource ids as opaque strings. Do not infer meaning from their format.

→Use GET endpoints to discover schema/state first, then POST to create, PATCH to update or move, DELETE only for explicit destructive actions.

Notes Memory Flow

→Use the API key as the user identity. Do not pass userId in Notes memory requests.

→Use one named folder as the memory namespace for a workflow, customer, project, or external app.

→Before acting, call POST /api/v1/notes/recall. After acting, append the raw event and upsert any distilled memory that changed.

→For MCP clients, connect to POST /api/mcp/notes with the same Bearer API key.

→Typical flow: POST /api/v1/notes/recall → act → POST /api/v1/notes/append → POST /api/v1/notes/upsert

MCP Client Flow

→Each MCP endpoint is HTTP JSON-RPC and accepts the same Authorization: Bearer token as REST.

→Send an Idempotency-Key header (or idempotencyKey in the body) with every submit. If the response never arrives, resend with the same key: you get the same job back, marked data.replayed: true, and are not charged again. Polls are safe to retry as they are.

→Clients that support OAuth can sign the user in through a browser instead of asking for a key. An unauthenticated call answers 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource.

→Call initialize once, then tools/list to discover available tool names and input schemas.

→Tool calls preserve the same credits, permissions, validation, and UI sync as the REST API.

→Available: /api/mcp/notes

→Authentication: Two ways in. Sign in through your client if it supports it - Bildy hands it a token, and nothing gets pasted anywhere. Otherwise store the API key in your agent's config and pass it as a Bearer token.

→UI sync: Templates, campaigns, posts, boards, and cards created via the API appear in the Bildy UI automatically.

→Credits: Check balance with GET /api/v1/credits before expensive operations.

→Error handling: Always check for 402 (insufficient credits) and prompt the user to start or manage their subscription.

Bildy API v1 · Questions? [email protected]