AI Prompts

These admin routes manage the AI surface for a project: register the provider key the project uses, define reusable prompt templates, and test-invoke them. End-user invocation from app code (Amba.ai.run()) is covered in the AI SDK guide; this page is the developer-side management API.

You bring your own provider key (Anthropic, OpenAI, Mistral, or Google Gemini). Register it once, then define prompts that reference it. All routes mount under /v1/admin/projects/:projectId/ai/*.

Endpoints

Providers

Register the key for anthropic, openai, mistral, or gemini. The key is stored encrypted; the response shows only a masked preview, never the full value.

curl -X POST 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/ai/providers' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "anthropic", "api_key": "sk-ant-…" }'

{ "data": { "name": "anthropic", "configured": true, "api_key_preview": "sk-ant…1234" } }

A provider can't be deleted while prompts still reference it — you get 409 PROVIDER_HAS_PROMPTS. Delete the prompts first.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/ai/providers'

POST /admin/projects/:projectId/ai/prompts

Register a prompt template. This is an upsert keyed on name: re-registering an existing name bumps its version. The referenced provider must already be registered, or you get 409 PROVIDER_NOT_REGISTERED.

Request

curl -X POST 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/ai/prompts' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "summarize",
    "provider": "anthropic",
    "model": "claude-sonnet-4-5-20250929",
    "system_prompt": "Summarize the user message in one sentence.",
    "max_tokens": 256,
    "client_invokable": true
  }'

Response 200

{
  "data": {
    "name": "summarize",
    "version": 1,
    "provider": "anthropic",
    "model": "claude-sonnet-4-5-20250929",
    "client_invokable": true
  }
}

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/ai/prompts'

GET /admin/projects/:projectId/ai/prompts

List every registered prompt with its full configuration.

{
  "data": [
    {
      "name": "summarize",
      "version": 1,
      "provider": "anthropic",
      "model": "claude-sonnet-4-5-20250929",
      "system_prompt": "Summarize the user message in one sentence.",
      "max_tokens": 256,
      "rate_limit": null,
      "client_invokable": true,
      "created_at": "…",
      "updated_at": "…"
    }
  ]
}

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/ai/prompts'

GET /admin/projects/:projectId/ai/prompts/:name

Describe one prompt (same row shape as the list). 404 NOT_FOUND if it isn't registered.

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/ai/prompts/%7B%7BpromptName%7D%7D'

DELETE /admin/projects/:projectId/ai/prompts/:name

Hard-delete a prompt. Any client invocation referencing the name afterwards returns 404.

{ "data": { "name": "summarize" } }

Try it:

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/ai/prompts/%7B%7BpromptName%7D%7D'

Prompt budgets

Each prompt can carry a spend budget — a per-period USD ceiling on its AI cost. Once the period's spend reaches the budget, further invocations are denied with a clear ai_budget_exceeded error (HTTP 429) until the period resets — so a prompt you've exposed to your app can't run away with spend. Budgets are off by default (unlimited).

This is the fine-grained sibling of the project-wide spend ceiling: that caps your whole project's monthly bill; a prompt budget caps one named prompt.

budget_period is the reset cadence: monthly (default — resets the first of each UTC month), daily (resets at UTC midnight), or total (never resets — a hard lifetime cap).

PUT /admin/projects/:projectId/ai/prompts/:name/budget

Set or clear a prompt's budget. Pass budget_usd as a dollar amount, or null to remove the budget.

curl -X PUT 'https://api.amba.dev/v1/admin/projects/$PROJECT_ID/ai/prompts/summarize/budget' \
  -H 'Authorization: Bearer $AMBA_PAT' \
  -H 'Content-Type: application/json' \
  -d '{ "budget_usd": 25, "budget_period": "monthly" }'

{ "data": { "name": "summarize", "budget_usd": 25, "budget_period": "monthly" } }

GET /admin/projects/:projectId/ai/prompts/:name/budget

Read the budget alongside the current period's spend.

{
  "data": {
    "name": "summarize",
    "budget_usd": 25,
    "budget_period": "monthly",
    "period_spend_usd": 2.25,
    "remaining_usd": 22.75,
    "exceeded": false
  }
}

GET /admin/projects/:projectId/ai/prompts/:name/spend

Current-period AI spend for the prompt, summed from every invocation's cost. Pass ?period=daily|monthly|total to inspect a different window.

{
  "data": {
    "name": "summarize",
    "period": "monthly",
    "period_start": "2026-06-01T00:00:00.000Z",
    "spend_usd": 2.25,
    "budget_usd": 25,
    "exceeded": false
  }
}

POST /admin/projects/:projectId/ai/messages

Raw passthrough — forward a provider-shaped body to your registered provider using the project's key. Useful for admin tooling and eval suites.

Request

{
  "provider": "anthropic",
  "body": {
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 256,
    "messages": [{ "role": "user", "content": "Hello" }]
  }
}

The provider's native response is returned verbatim.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/ai/messages'

POST /admin/projects/:projectId/ai/embeddings

Generate embeddings through the registered provider. Body { provider, model, input } where input is a string or array of strings. Returns { data: { embeddings, usage } }. (Embeddings are supported on openai.)

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/ai/embeddings'

MCP tools

amba_ai_prompts_create, amba_ai_prompts_list, amba_ai_prompts_get, amba_ai_prompts_update, amba_ai_prompts_delete, and amba_ai_prompts_invoke wrap the prompt routes for agentic use. amba_ai_prompts_invoke resolves a registered prompt by name and proxies a test invocation through the passthrough — pass the prompt name and a provider-shaped messages array. To test a vision prompt, pass images (each { url } or { data, mime }); they attach to the last user message and are mapped to the model's native image format. The prompt's model must be vision-capable.

amba_ai_prompts_set_budget and amba_ai_prompts_get_spend manage and inspect a prompt's spend budget — set a per-period USD ceiling, then read the live spend and remaining headroom.