> For the complete documentation index, see [llms.txt](https://docs.limecall.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limecall.com/developers.md).

# Developers

The LimeCall REST API, authentication, webhooks and limits.

LimeCall has two separate surfaces with two separate kinds of key. Mixing them up is the single most common integration mistake, so start here:

```mermaid
flowchart LR
    subgraph B["Browser — your website"]
      W["Widget<br/>window.LimeCall"]
    end
    subgraph S["Your server"]
      A["Your backend"]
    end
    W -- "X-Widget-Key<br/>publishable" --> P["/api/public/callback<br/>Request a call"]
    A -- "Authorization: Bearer<br/>sk_live_ — SECRET" --> R["/api/v1<br/>Calls, contacts, numbers"]
```

The **widget key** is already in your page source and is meant to be public. The **secret key** must never reach a browser. They are not interchangeable, and neither surface accepts the other's key.

## Base URL

```
https://app.limecall.com/api/v1
```

## Authentication

Every request carries a bearer token:

```
Authorization: Bearer sk_live_...
```

Create tokens under **Settings → API keys**, or on the **Developers** page in the dashboard. See [API keys](/developers/api-keys.md).

## A first request

```bash
curl https://app.limecall.com/api/v1/calls \
  -H "Authorization: Bearer sk_live_..."
```

## Writing an outcome back

The most valuable single call in the API. When a call turns into a booking or a sale, write that back and it appears on the call and in your totals:

```bash
curl -X PATCH https://app.limecall.com/api/v1/calls/{callId} \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"outcome":"appointment_booked","value":250,"currency":"USD"}'
```

The outcome name is yours — use the same one consistently and calls group by it. Sending `value` is what lets LimeCall report revenue by channel rather than call counts by channel. See [Conversions](/analytics/conversions.md).

Requires a token with write access.

## Content type

Send `Content-Type: application/json` on requests with a body. Responses are JSON.

## This API is not the dashboard's API

The `/api/v1` surface is the customer-facing API, authenticated with `sk_live_` tokens. The dashboard itself uses a separate internal API with session authentication.

Only `/api/v1` is supported for integration. Anything you find by watching the dashboard's network traffic is internal, undocumented and will change without notice.

## Endpoint reference

| Resource                                      | Endpoints | Covers                                                               |
| --------------------------------------------- | --------- | -------------------------------------------------------------------- |
| [Calls](/developers/calls.md)                 | 7         | List, inspect, recordings, transcripts, summaries, outcome writeback |
| [Messages](/developers/messages.md)           | 3         | Send SMS/MMS, list history                                           |
| [Contacts](/developers/contacts.md)           | 5         | Full CRUD                                                            |
| [Phone numbers](/developers/phone-numbers.md) | 3         | List and reconfigure your lines                                      |
| [Voicemails](/developers/voicemails.md)       | 2         | List and mark handled                                                |
| [Users](/developers/users.md)                 | 5         | Your team, and verified caller-ID numbers                            |
| [Webhooks](/developers/webhooks.md)           | 5         | Manage subscriptions                                                 |
| [Analytics](/developers/analytics.md)         | 3         | Usage and breakdowns                                                 |
| [Devices](/developers/devices.md)             | 2         | Push tokens, for your own client                                     |

## Also in this section

* [API keys](/developers/api-keys.md) — creating and scoping tokens
* [Webhook events](/developers/webhook-events.md) — the events and how to handle them
* [Errors, pagination & rate limits](/developers/errors-and-rate-limits.md) — status codes, paging and limits

## Working in the browser instead

The REST API is for your server. To drive the callback widget from your own page — open it on a button, fire it from a form you already have, listen for events — use the browser API, which needs no secret key:

* [JavaScript API](/callback/javascript-api.md)
* [Connect your own form](/callback/connect-your-own-form.md)

## No-code alternatives

If you do not want to write code, Zapier, Make and n8n cover most integration needs. See [Zapier, Make & n8n](/integrations/zapier-and-make.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.limecall.com/developers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.