BottleCRM
Get started

Connect your AI

BottleCRM has a complete REST API, and an AI agent uses it the same way any other program does: an HTTPS request with a token in the header. Ask your agent to "show my open leads this week", "create a contact for Acme Corp", or "summarize what happened on the Acme account", and it works through that API.

The agent acts as you. It authenticates with a personal access token and inherits exactly your role and your organization's data, never more. Every request is checked by the same permissions, validation, and tenant isolation that guard the web app.

Which agents can use this. Anything that can make an authenticated HTTP request: Claude Code, Cursor, Codex CLI, Gemini CLI, an n8n or Zapier step, or an agent you build yourself with the Claude or OpenAI SDKs. Chat apps that can only reach the internet through a prebuilt connector are the exception, since they need someone to build that connector first.

How it works

There is no middle layer. Your agent calls the API directly, and the backend is the only trust boundary.

You, in your AI client                     Your BottleCRM
──────────────────────                     ──────────────
"Show my open leads"  ─────────────▶  REST API (auth + permissions
                       Bearer token         + RLS + validation)
"Here are 12 leads…"  ◀─────────────  JSON

Because every action goes through the API, the agent cannot bypass a security rule. There is no elevated service account and no separate agent identity.

Step 1: Create a personal access token

  1. Open the BottleCRM app (https://app.bottlecrm.io, or your own app domain) and go to Settings → API Tokens.
  2. Click Create token, give it a recognizable name (for example "Claude research agent"), and optionally set an expiry.
  3. Copy the token (it starts with bcrm_pat_) immediately. It is shown only once and can never be retrieved again.

A token carries your identity. Anyone who has it can do what you can do in your org, so treat it like a password. You can revoke it from the same page at any time, and the next request from that token will fail.

Step 2: Point your agent at the API

Give the agent three things: the API base URL, the token, and the schema.

curl -H "Authorization: Bearer bcrm_pat_…" \
     "https://api.bottlecrm.io/api/leads/?status=open&limit=20"
What to give it Value
Base URL https://api.bottlecrm.io for hosted BottleCRM, or your own API domain if you self-host.
Auth header Authorization: Bearer bcrm_pat_… on every request.
Schema https://api.bottlecrm.io/schema/ returns the full OpenAPI 3 description.

That last row is the one people skip. Hand the agent the OpenAPI schema and it works out the endpoints, the request bodies, the enums and the required fields on its own. You do not have to describe the API to it by hand, and it stays correct as the API grows.

For a coding agent, the fastest setup is to put the base URL and the schema URL in its project instructions, and the token in an environment variable it can read.

Step 3: Start asking

Talk to the agent in plain language. It picks the endpoints. A few things that work well:

  • "Which deals are closing this month, and which have had no activity in two weeks?"
  • "Create a contact for Priya at Acme Corp and link it to their account."
  • "Summarize the last five support tickets for this customer."
  • "Move every lead older than 90 days with no contact to lost."

What the agent can reach

Everything the API exposes, which is everything in the product: leads, contacts, accounts, opportunities, tasks, cases, solutions, invoices, estimates, recurring invoices, products, documents, goals, timesheets, approvals, tags, custom fields and reporting.

Worked examples in Python and JavaScript show the request shapes.

Security and safety

  • Acts as you, never more. The agent inherits your role and org. A sales rep's agent is limited to what the rep can do. It cannot see another team's or another company's data.
  • Tenant isolation is enforced server-side. PostgreSQL row-level security scopes every query to your organization.
  • Revocable and expirable. Cut off an agent instantly by revoking its token, or set an expiry up front. Admins can revoke any token in the org from Settings → API Tokens.
  • Deactivating a person cuts their agent off too. A token stops working the moment its owner's profile is deactivated.
  • Tokens stay secret. Only a hash is stored. The raw token is shown once and never logged. Keep it out of source control and shared configs.
  • Put a human in front of irreversible actions. The API will delete a record or email an invoice to a customer if asked. It does not ask twice. If you let an agent run unattended, give it a token belonging to a read-only-ish role, or require confirmation in your own agent's logic.

Troubleshooting

  • The agent gets a 401. Check the header reads Authorization: Bearer bcrm_pat_… and that the token is current, not revoked or expired.
  • The agent gets a 403, or sees no rows. The token's owner does not have access to that record or that org. This is working as intended. Check the owning profile's role.
  • The token was lost. Tokens cannot be recovered. Create a new one and revoke the old.
  • The agent guesses wrong field names. Give it the schema URL. Most of these problems are the agent working from memory instead of from /schema/.