# API Reference

> Flamel's REST API and MCP server — authenticate with OAuth 2.1, explore endpoints, and integrate Flamel data into your tools.

<Callout type="info" title="REST API access">
The MCP server below is open to every Flamel user: sign in with your Flamel account. The REST API is currently available to staff and select partners. Contact your account manager or email `support@flamel.ai` to request REST access. Hub admins who only need to read their own hub's opt-ins and spend can create a key themselves with the [Hub API](/manage/hub/api).
</Callout>

Flamel exposes a REST API and an MCP server so you can integrate Flamel data and actions into your own tools, dashboards, and AI agents. Both share the same OAuth 2.1 authentication.

## Authentication

Flamel uses OAuth 2.1 with the authorization code flow and PKCE. Tokens are issued per user and carry the `flamel:full` scope. The endpoints below are discoverable at `https://studio.flamel.ai/.well-known/oauth-authorization-server`.

| Endpoint | URL |
|---|---|
| Authorization | `https://studio.flamel.ai/api/oauth/authorize` |
| Token | `https://studio.flamel.ai/api/oauth/token` |
| Client registration | `https://studio.flamel.ai/api/oauth/register` |
| Token revocation | `https://studio.flamel.ai/api/oauth/revoke` |

Supported grant types are `authorization_code` and `refresh_token`. The only `code_challenge_method` is `S256`, and the only scope is `flamel:full`.

<Steps>
<Step>
### Register a client

If your account manager has not pre-provisioned a client, register one with dynamic client registration. You receive back a `client_id` (and a `client_secret` if you request a confidential client).

```bash
curl -X POST https://studio.flamel.ai/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Integration",
    "redirect_uris": ["https://your-app.example.com/callback"],
    "token_endpoint_auth_method": "client_secret_post"
  }'
```

For a public (PKCE-only) client, send `"token_endpoint_auth_method": "none"` and omit the secret on token exchange.
</Step>
<Step>
### Send the user through authorization

Generate a PKCE `code_verifier` and its `code_challenge` (`S256`), then redirect the user to the authorization endpoint. After they approve the consent screen, Flamel redirects back to your `redirect_uri` with a `code` query parameter.

```
https://studio.flamel.ai/api/oauth/authorize
  ?response_type=code
  &client_id=<your_client_id>
  &redirect_uri=https://your-app.example.com/callback
  &code_challenge=<your_code_challenge>
  &code_challenge_method=S256
  &scope=flamel:full
```
</Step>
<Step>
### Exchange the code for a bearer token

Post the authorization code and your PKCE `code_verifier` to the token endpoint:

```bash
curl -X POST https://studio.flamel.ai/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=<authorization_code>" \
  -d "redirect_uri=https://your-app.example.com/callback" \
  -d "client_id=<your_client_id>" \
  -d "client_secret=<your_client_secret>" \
  -d "code_verifier=<your_code_verifier>"
```

The response contains your `access_token`. Include it in the `Authorization` header of every request:

```
Authorization: Bearer <your_access_token>
```

When the access token expires, request a new one with `grant_type=refresh_token` and the `refresh_token` from this response.
</Step>
<Step>
### Confirm authentication

Use the MCP server's `whoami` tool (see below) to confirm your token works. It returns your authenticated user, active workspace, active hub, scope, and client ID:

```json
{
  "user": { "_id": "...", "email": "you@example.com", "firstname": "...", "lastname": "..." },
  "workspace": { "_id": "...", "name": "Downtown Location" },
  "hub": { "_id": "...", "name": "Acme Franchising" },
  "scope": "flamel:full",
  "clientId": "<your_client_id>"
}
```
</Step>
</Steps>

## MCP server

The MCP server at `https://studio.flamel.ai/api/mcp` is the primary integration surface for AI agents. It uses the same OAuth flow as above, so you sign in with your Flamel account and the client discovers the available tools automatically. Each tool runs with your own role and solution permissions in the hub or workspace you choose.

### Connect your AI client

The fastest path is the **Flamel MCP** page at [studio.flamel.ai/mcp/docs](https://studio.flamel.ai/mcp/docs). It shows the server URL with a copy button, setup steps for each client, and the skills your access allows.

<Tabs items={["Claude", "ChatGPT", "Cursor", "Claude Code", "Other agents"]}>
<Tab value="Claude">
Open **Settings**, then **Connectors**, then **Add custom connector**. Paste the server URL and sign in to Flamel.
</Tab>
<Tab value="ChatGPT">
A ChatGPT workspace admin turns on developer mode, adds the server URL as a custom app, and signs in to Flamel.
</Tab>
<Tab value="Cursor">
Open **Settings**, then **MCP**, then **Add new MCP server**, or add this to `~/.cursor/mcp.json`. Sign in when Cursor asks.

```json
{ "mcpServers": { "flamel": { "url": "https://studio.flamel.ai/api/mcp" } } }
```
</Tab>
<Tab value="Claude Code">
Run this command, then finish sign-in with `/mcp`.

```bash
claude mcp add --transport http flamel https://studio.flamel.ai/api/mcp
```
</Tab>
<Tab value="Other agents">
Any agent harness that supports remote MCP servers with OAuth, such as Scout, connects the same way. Add the server URL as a remote MCP server and complete the Flamel sign-in when the harness opens it.
</Tab>
</Tabs>

After you connect, ask your client to use the `connect-flamel` skill. It confirms who you are signed in as, which hub or workspace is active, and which skills you can use.

### Get your skills

Skills are step-by-step instructions that teach your AI client how to do a Flamel task well. Your client can load them through the `query_flamel_skills` tool, or you can install them yourself.

<Steps>
<Step>
### Open the Flamel MCP page

Sign in to Studio and go to [studio.flamel.ai/mcp/docs](https://studio.flamel.ai/mcp/docs).
</Step>
<Step>
### Pick your hub or workspace

Use the switcher to choose the hub or workspace you want the client to work in. The skill list and downloads match what you can do in the hub or workspace you have selected.
</Step>
<Step>
### Download a skill

Click **Download** on a skill to get it as a zip. Upload the zip to Claude as a skill, which an organization owner can do once for everyone, or unzip it into `~/.claude/skills/` for Claude Code.
</Step>
</Steps>

You see a skill only when your account can use every tool it needs. Paid skills require the matching solution on your account, such as **Meta Ads**, **Google Ads**, or **ChatGPT Ads**, with the permissions required by that skill. If a skill you expect is missing, ask a hub admin to grant the solution.

| Skill | What it does |
|---|---|
| `connect-flamel` | Confirms your connection, active scope, and the skills you can use. |
| `paid-performance-report` | Reports paid spend, CPC, CPM, CTR, and leads by workspace and playbook for a date range. |
| `weekly-report` | Builds a cross-channel performance report for a date range and audience you choose. |
| `chatgpt-ads-report` | Shows how ChatGPT Ads are set up and performing, including spend, results, and workspace readiness. |
| `playbook-health` | Finds playbooks and opt-ins that are failing, stuck, or not launching, and ranks the fixes. |
| `build-playbook` | Drafts a full Meta or Google Ads playbook with campaigns, creative, targeting, and budget from a brief. |
| `opt-in-playbook` | Localizes a hub playbook for a workspace and opts it in, or changes or cancels an opt-in. |
| `create-command-center` | Creates a paid Command Center or alert rules for chosen workspaces and campaigns. |
| `manage-command-center` | Reviews and adjusts campaign status, pacing, budgets, and alerts in a Command Center. |
| `analyze-and-tune` | Diagnoses paid and cross-channel performance and previews evidence-backed changes. |
| `configure-meta-ads` | Audits and completes a workspace's Meta Ads setup, defaults, URLs, audiences, and lead forms. |
| `configure-google-ads` | Audits and completes a workspace's Google Ads connection, defaults, attribution, URLs, and targeting. |
| `triage-signals` | Works through open items on the Signals page, from what needs attention to the fix. |

### How changes are approved

Every change starts as a preview that changes no campaign, budget, or setting. Flamel applies it only after you give an explicit yes to that exact preview, and anything that adds or raises ad spend shows the dollar amounts first. A read-only connection can preview changes but cannot apply them.

## REST endpoints

The REST API shares the same bearer token. Base URL:

```
https://studio.flamel.ai/api
```

### Hubs and workspaces

| Method | Path | Description |
|---|---|---|
| GET | `/workspaces` | List all workspaces in your hub |
| GET | `/workspaces/:id` | Get details for a specific workspace |
| GET | `/hubs` | List all hubs in your account |

### Content

| Method | Path | Description |
|---|---|---|
| GET | `/posts` | List scheduled and published posts |
| POST | `/posts` | Create a new post |
| GET | `/media` | List media library assets |
| POST | `/media` | Upload a media asset |

### Analytics

| Method | Path | Description |
|---|---|---|
| GET | `/analytics/organic` | Retrieve organic post performance |
| GET | `/analytics/paid` | Retrieve paid campaign performance |
| GET | `/analytics/google-reviews` | Retrieve Google Review summaries |

<Callout type="info" title="Request bodies and field-level schemas">
The write endpoints (`POST /posts`, `POST /media`) accept the same payloads the in-app composer and uploader send. Because those shapes evolve with the product, contact `support@flamel.ai` for the current field-level schema for any write endpoint rather than relying on a fixed copy here.
</Callout>

## Rate limits

| Plan | Requests per minute |
|---|---|
| Standard | 60 |
| Partner | 300 |

Requests exceeding the limit receive `429 Too Many Requests` with a `Retry-After` header.

## Error codes

| Code | Meaning |
|---|---|
| 400 | Bad Request: check your request body or query parameters |
| 401 | Unauthorized: token missing, expired, or invalid |
| 403 | Forbidden: token lacks the required scope |
| 404 | Not Found: resource does not exist or is inaccessible |
| 429 | Rate Limited: retry after the indicated delay |
| 500 | Server Error: contact support if this persists |

<Cards>

<Card title="Getting Started" href="/getting-started" icon="rocket">
Overview of the Flamel platform before diving into the API.
</Card>

<Card title="Glossary" href="/glossary" icon="book">
Definitions for Hub, Workspace, Playbook, and other terms used in API responses.
</Card>

</Cards>

---

Source: [https://docs.flamel.ai/api](https://docs.flamel.ai/api)
Docs MCP server: https://docs.flamel.ai/mcp · Marketing content: https://www.flamel.ai/mcp
