For AI agents

You are probably an autonomous coding agent or an LLM-driven client reading this to learn how to use Nimblesite. This page is the briefing: it gives you the live, machine-readable contract, the auth model, the full request loop, and pointers to every other doc. Read this once and you have enough to integrate end-to-end without a human.

Start here — the live contract

The OpenAPI document is the single source of truth. Every endpoint, request body, response schema, status code, and error is described there. Fetch it first and generate a typed client; do not hand-transcribe endpoints from prose.

OpenAPI JSON — fetch this first → Live Swagger UI → ReDoc →

The spec is public — you do not need an API key to read /openapi.json, /docs, or /redoc. You only need a key to make real calls.

What Nimblesite is

Nimblesite is prepaid, predictable Agents as a Service. You POST one JSON config and get back a stable HTTP endpoint that behaves like a stateful agent — conversation memory, tools, multi-tenancy, prompt templates, prepaid spend controls, and your choice of model, all already wired up. You never build a messages table, replay history, or hand-roll the tool loop. See the Introduction for the full pitch.

Base URL and authentication

• Base URL: https://api.nimblesite.ai
• All API endpoints live under /api/v1/
• Auth header: X-API-Key: <your-key> on every API call. The key scopes every request to exactly one tenant — that is how isolation is enforced.
• Get a key (free): create an account, verify your email, sign in for a JWT, then POST /api/v1/tenants with Authorization: Bearer <jwt>. The response returns your first API key once (only a SHA-256 hash is stored). Account, tenant, and key creation cost nothing — credit is only spent on chat/tool/workspace calls. The full sign-up, verify, and sign-in URLs are published in /openapi.json under x-auth.

export NIMBLE_KEY="<your-api-key>"

Onboarding & auth — read the spec's x-auth metadata first

Everything needed to go from no account to a working key is encoded in the OpenAPI document itself — you do not have to scrape this page:

• description (top of /openapi.json) embeds the full auth walk-through and a provisioning-bundle upload walk-through in prose.
• x-auth.endpoints is the machine-readable block of auth-service URLs: signup, signin, refresh, verify, recover, magic_link, user. Every auth-service call also needs the platform anon key as the apikey header (its value is in the description).
• components.securitySchemes describes BearerJWT (the access token from signin) and TenantApiKey (the X-API-Key).

Canonical onboarding order — steps 1–4 are free; credit only applies once you chat:

1. Create a user. POST the x-auth.endpoints.signup URL with {"email","password"} and the apikey header. A verification email is sent.
2. Verify the email. The user clicks the link. Tenant creation is gated on it: an unverified caller gets 403 email_not_verified.
3. Sign in. POST the x-auth.endpoints.signin URL; the response holds access_token (the JWT) and refresh_token.
4. Create a tenant. POST /api/v1/tenants with Authorization: Bearer <access_token>. You become the owner and the response returns your first api_key once. Use it as X-API-Key, or keep the JWT with X-Tenant-Id.

For sandboxed (embodied) agents, the same OpenAPI description documents the provisioning-bundle upload flow: POST /api/v1/bundles (raw .tgz, ≤ 50 MiB), then pin the returned url + sha256 onto the config's provisioning_bundle. See Tools and Agent execution modes.

Minimal integration — two calls

1. Define an agent (once)

curl -X POST https://api.nimblesite.ai/api/v1/configs \
  -H "X-API-Key: $NIMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hello Agent",
    "system_prompt": "You are a helpful assistant for {tenant_name}.",
    "model_config": {"provider": "anthropic", "model": "claude-sonnet-4-6"},
    "tools_config": []
  }'

The response contains an id field — that is your config_id. Save it.

2. Talk to it (forever)

curl -X POST https://api.nimblesite.ai/api/v1/chat/$CONFIG_ID \
  -H "X-API-Key: $NIMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello! Who are you?"}'

The response carries response, a conversation_id, and a tool_calls array. Send the same conversation_id on the next call and the agent remembers everything — you store nothing. Full request/response shape: Chat & conversations.

The tool-call loop you must implement

For client-side agents (agent_type: "disembodied"), the agent decides what to call and your code runs it. Nimblesite never executes your tools or holds your secrets. The loop:

1. POST a message to /api/v1/chat/{config_id}.
2. If the response tool_calls array is non-empty, execute each call locally ({id, name, arguments}).
3. POST the results back on the same conversation_id:

{
  "conversation_id": "11111111-1111-1111-1111-111111111111",
  "tool_results": [
    {"tool_call_id": "call_01", "name": "write_file", "content": "ok", "ok": true}
  ]
}

4. Repeat until a response carries text and an empty tool_calls array — that is the end of the turn.

If you'd rather Nimblesite host the tools too (real filesystem + shell in a managed container), use sandboxed mode and the client only ever sees final text. Full contract: Tools and Agent execution modes.

Hard rules every integrator must respect

• Prepaid credit gate. Billable calls (chat, model usage) fail with HTTP 402 when the tenant has no prepaid credit. Top up before retrying; do not hammer. See Pricing.
• Tenant isolation. One X-API-Key = one tenant. Never share a key across tenants; use separate keys for prod, staging, CI, and partner traffic. See Multi-tenancy.
• conversation_id is memory, not auth. It does not authenticate an end user. Authentication is the X-API-Key (tenant scope); binding a conversation to one of your users is your app's job. See Chat & conversations.
• You execute client-side tools. Nimblesite emits tool calls; it never runs your code, touches your data, or sees your secrets. That is deliberate — read why.
• Model input leaves to the provider. Everything you and your end-users send to a model is forwarded to that model's provider and handled under their privacy policy — Nimblesite cannot control what they do with it. Your users will enter personal data; it is your job to tell them. See Privacy.
• Found a security issue? Report it — see For cyber security professionals. Test only against your own tenant; never another tenant's data.

Capability map — every doc, one table

Recommended agent workflow

1. Fetch https://api.nimblesite.ai/openapi.json and parse it — this is your authoritative map of every operation and schema.
2. Register and verify your email (auth-service URLs are in /openapi.json under x-auth), then sign in for a JWT. Email verification is required before the next step.
3. Create your tenant (POST /api/v1/tenants with the JWT); save the api_key it returns once and set X-API-Key.
4. Create a config (POST /api/v1/configs); keep the returned id (your config_id).
5. Chat (POST /api/v1/chat/{config_id}); keep the returned conversation_id, and run the tool loop above if tool_calls is non-empty.
6. Handle 402 — steps 2–4 are free; only chat/tool/workspace calls bill against prepaid credit, so top up when the balance is exhausted. Handle other 4xx per the schemas in the spec.

Ready to integrate? Get an API key → Open the live Swagger UI →