Straightline Straightline
User Guide / Api And Mcp

API & MCP

Overview

Everything Straightline does through the interface, it also does through an API — and that same API is exposed to Claude through a Model Context Protocol (MCP) connector.

There are two ways in, and one credential for both:

  • REST API at /api/v1/ — for scripts, integrations and your own tooling. Browse it at /api/v1/docs/.
  • MCP server at /mcp — for Claude Desktop, Claude Code and any other MCP client.

Both are available on every plan.

API tokens

Go to Account → API & MCP to create one.

A token acts as you, inside your current organization, with your role's permissions. It cannot reach another organization and cannot do anything your role could not do in the interface.

Scopes

Scope What it allows
Read only Every list and detail endpoint. Nothing is created, changed or sent.
Read and write Everything above, plus creating and updating records and sending messages.

Start with a read-only token. Issue a write token when you want Claude — or your script — to actually change things.

Keeping a token safe

The raw token is shown once, at creation. Straightline stores only a SHA-256 hash of it, so nobody — including us — can recover it later. If you lose it, revoke it and create another.

Revoking is instant: the token stops working on the next request. Revoked tokens stay in the list so you keep the history.

Every request records a "last used" timestamp, so an unused token is easy to spot and retire.

Using the REST API

Send the token as a bearer credential:

curl https://your-straightline-host/api/v1/leads/?status=qualified \
  -H "Authorization: Bearer sl_your_token_here"

Or as X-API-Key, if that suits your client better.

What's covered

Path Contents
/api/v1/me/ Who this token is, which organization, which role
/api/v1/leads/ Leads, plus notes, tags, qualify and convert actions
/api/v1/contacts/ Contacts, plus notes, tags, activities, messages, and send actions
/api/v1/automations/ Automations, steps, run logs, activate and deactivate
/api/v1/resources/ Content resources, plus sending one to a contact
/api/v1/sources/ Lead sources
/api/v1/forms/ Website capture forms and their embed snippets
/api/v1/seo/websites/ Sites an SEO agent works on, and the competitors tracked against each
/api/v1/seo/feeds/ Content feeds — the tag set each website shows, and how it renders
/api/v1/seo/agents/ SEO agents, their limits, and whether anything is stopping them
/api/v1/seo/keywords/ Proposed phrases with the evidence behind each score (read-only)
/api/v1/seo/topics/ Topics — several keywords, one article — with approve, reject and write
/api/v1/seo/jobs/ Research and writing passes, to poll after asking for one
/api/v1/seo/events/ What the agents have done, and whether anybody asked
/api/v1/deals/ Pipeline, plus stage changes
/api/v1/messages/, /api/v1/activities/ Read-only history across the organization
/api/v1/reports/revenue-summary/ Funnel and pipeline for a rolling window
/api/v1/usage/ Plan limits against current usage

Lists are paginated at 25 rows by default, capped at 100 with ?page_size=. Most lists accept ?q= for free-text search plus a few exact filters — the interactive docs at /api/v1/docs/ list them per endpoint.

The full OpenAPI schema is at /api/v1/schema/.

Connecting Claude

Create a token, then run:

claude mcp add --transport http straightline https://your-straightline-host/mcp \
  --header "Authorization: Bearer sl_your_token_here"

Claude now has around 37 tools covering leads, contacts, conversations, automations, resources, sources, forms, deals and reporting. Ask in plain language:

  • "Which leads came in from the pricing page this week, and which are worth a call?"
  • "Read Dana's history and draft a follow-up that picks up where we left off."
  • "Set up a capture form for the new campaign page and give me the embed code."
  • "How did the funnel move this quarter, and where did it leak?"

What Claude can and cannot do

  • It cannot leave your organization. No tool takes an organization argument. The token decides, and it cannot be overridden by anything typed into a chat.
  • A read-only token hides the write tools entirely. They are not listed, so Claude will not attempt them.
  • Sending is flagged. Tools that send email or SMS, or that switch an automation on, are marked as destructive so Claude asks before running them. Confirm the recipients and the wording before you say yes.
  • Everything is logged. Each tool call writes to your organization's audit trail as mcp_<tool name>, attributed to the token's user. See Tenant Settings → Audit Trail.

If something goes wrong

What you see What it means
Invalid API token The token was mistyped, or it was never issued in this organization.
This API token has been revoked Create a new one under Account → API & MCP.
needs a write-scoped token The token is read-only. Issue a read/write token for that action.
Your role does not permit this action The token inherits your role. Ask an administrator to widen it.
has no email configuration Sending needs SMTP set up under Tenant Settings → Email.

The public embed API

Separate from all of the above, /api/v1/embed/ serves your website: it accepts capture-form submissions and publishes your resources feed. It needs no token, because it is designed to be called from a browser — access is controlled by each form's origin allowlist and by the Feed Key under Account → Feed Key.

The Feed Key is read-only and published-only. It returns the resources you have published and nothing else — it cannot change anything, and it cannot see drafts. That matters because it is public by design: the embed script puts it in your page source. Anything that needs to write goes through a platform API token instead, which is hashed, scoped and never published.

Replace the Feed Key whenever you like — there is no waiting period. The old one stops working immediately, so update anywhere it is in use.

Server-rendered feeds

The JavaScript embed builds a feed in the browser after the page loads, so a search engine's first fetch sees an empty container. These three routes return the same content already rendered, for your own server to fetch while it builds the page. All take api_key and feed (the feed's slug), and are cached for five minutes.

Route Returns
/api/v1/embed/resources/html/ The feed as an HTML fragment — a listing, or whole articles, depending on the feed's render mode
/api/v1/embed/resources/<slug>/html/ One article, with its canonical link and structured data
/api/v1/embed/resources/sitemap.xml The feed's articles as a sitemap, for your sitemap index

The fragments carry no styling of their own, so they take your page's. The article markup is reduced to a safe subset on the way out.

/api/v1/embed/resources/ also accepts ?include=body, which adds the article text and search metadata to the JSON if you would rather build the markup yourself.