Bildy
0
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

  1. 1Get an API key - Sign in and generate a key below.
  2. 2Add the header - Include Authorization: Bearer bld_YOUR_KEY in every request.
  3. 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 manifestOpen 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.
Loading...

Rate Limits

  • Requests per minute60
  • Max request body10 KB
  • Timeout30s

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
  • 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"
  }
}
StatusCodeMeaning
400bad_requestMissing or invalid fields
400invalid_json_bodyMalformed JSON request body
415unsupported_media_typeContent-Type must be application/json
401unauthorizedMissing, invalid or revoked credential. The response carries a WWW-Authenticate header naming the sign-in flow.
402insufficient_creditsNot enough credits
429rate_limitedToo many requests - check Retry-After header
500provider_config_errorProvider env config missing on server
500auth_config_errorAPI key verification service misconfigured
502upstream_service_errorUpstream provider request failed
502response_parse_errorProvider output was not parseable JSON
502response_format_errorProvider output had no JSON object
500internal_errorServer 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.
→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]