# 1Snag API > 1Snag is a lead inbox and pipeline for small businesses: leads, their conversations, scores and qualification, > campaigns and follow-up sequences, deals, and analytics, for one company workspace at a time. This file tells an AI > agent how to use its API and MCP connector safely. Base URL: https://api.leads.adrianwisely.com/v1/1snag All times in requests are Unix seconds; responses render them as ISO-8601. ## Start here - [OpenAPI 3.1 document](https://api.leads.adrianwisely.com/v1/1snag/openapi.json): every route with its scopes, parameters, bodies and a description of when to use it, what it costs and how to retry it. - [MCP connector](https://api.leads.adrianwisely.com/mcp): Streamable HTTP with OAuth 2.1 (dynamic client registration, PKCE). A person approves the permissions in the 1Snag dashboard; only tools the approved scopes allow are listed. A typical agent session: 1. `GET /usage/summary` (`get_usage`): what is left this period. Stop before a bulk action when a meter you need is in `blocked_meters`. 2. `GET /hot-leads?since=` (`list_hot_leads`) or `GET /leads?score_band=hot&sort=priority` (`search_leads`): who to work on now. 3. `GET /leads/{id}`, `GET /leads/{id}/score`, `GET /leads/{id}/qualification`: context, why the lead scores as it does, and the next question worth asking. 4. Record what you learn: `POST /interactions` (`log_interaction`), `POST /leads/{id}/qualification/answers` (`record_qualification_answer`). 5. Draft, never send on your own: campaign and reply drafts wait for a person's approval unless the workspace granted send scopes. 6. Report problems with 1Snag itself: `POST /feedback` (`send_feedback`). ## Authentication and scopes Send `Authorization: Bearer `. A workspace owner or administrator creates keys in Settings, API and integrations; each key carries only the scopes chosen for it and expires within 90 days. A key never inherits a person's role, cannot create keys, register webhooks, manage members, release compliance flags or record consent. A missing scope is `403` naming the scope. Scopes (risk: read, write, or contact = reaches a person or spends money): - `1snag:leads:read` (read, MCP default): Read leads, their timelines, consent, scores, qualification and segments, products, sources, campaigns and recipients - `1snag:leads:write` (write): Add and update leads, record qualification answers, assign products, log interactions, add sources and record opt-outs - `1snag:analytics:read` (read, MCP default): Read pipeline, source and product performance - `1snag:email:read` (read, MCP default): Read company email domains, mailboxes, addresses and conversations you can access - `1snag:email:manage` (write): Register email domains and reserve mailboxes and addresses - `1snag:email:draft` (write): Draft email replies (does not send) - `1snag:email:approve` (write): Approve or reject drafted email replies - `1snag:email:send` (contact): Send approved email replies to recipients - `1snag:campaign:read` (read, MCP default): Read campaign drafts, delivery status and recipient readiness - `1snag:campaign:manage` (write): Create draft campaigns and add or remove campaign recipients (does not send) - `1snag:campaign:draft` (write): Draft campaign emails (does not send) - `1snag:campaign:approve` (write): Approve or reject campaign drafts - `1snag:campaign:send` (contact): Send approved campaign emails to recipients - `1snag:sequences:read` (read): Read follow-up sequences, enrolled leads and each run's execution log - `1snag:sequences:enroll` (contact): Enrol leads in published follow-up sequences (which then email them) and pause or cancel runs - `1snag:messages:read` (read): Read WhatsApp, Telegram, Instagram and Messenger conversations and their messages - `1snag:messages:draft` (write): Draft WhatsApp, Instagram and Messenger replies into the approval queue (a person approves before anything is sent) - `1snag:appointments:write` (contact): Book, reschedule and cancel appointments for leads (the lead is emailed the invitation or change) - `1snag:usage:read` (read, MCP default): Read plan usage, remaining allowances, prepaid credits and the AI cap (no invoices or prices) - `1snag:feedback:write` (write, MCP default): Send product feedback (bugs, ideas, questions) to the 1Snag team; never to your contacts - `1snag:agents:run` (write): Run research agents over leads (uses AI calls; results are applied to leads only by a person or with 1snag:leads:write) - `1snag:sourcing:read` (read): Read lead searches (Find leads), the records they found and the exclusion list - `1snag:sourcing:run` (contact): Find new leads with the workspace's lead source and import them (spends sourcing units; imported leads can then be contacted) - `memory:read` (read): Search and retrieve this company's agent memory (verified lessons, facts and rules) - `memory:write` (write): Record observations and propose lessons to agent memory, and report whether they helped (people verify them) - `1snag:campaigns:write` (write): Create and change promo codes, partners and tracked links, and read campaign results (no payouts) - `1snag:conversions:write` (write): Check promo codes and report sign-ups, purchases and refunds from your product (server to server) - `1snag:funnels:read` (read): Read rep links, lead engagement, the call list (who to call now) and funnel stats - `1snag:funnels:write` (write): Create and change members' rep links (personal funnel links) - `1snag:academy:read` (read): Read the team academy (courses, lessons, completion), team goals and the leaderboard - `1snag:academy:write` (write): Create and change academy courses and lessons, and set team goals - `1snag:handoff:write` (write, MCP default): Ask a person in your company to look at something the assistant cannot handle (shown in "Needs you"; a named conversation the AI agent was handling is queued for a person) - `1snag:support:ingest` (contact): Post your product's customer messages to the AI support agent and read its answers; uses AI calls and, in Auto mode, answers your customers (for your product's server, not an assistant) - `1snag:payments:read` (read): Look up a customer's subscriptions, invoices, payments and refunds at your own connected payment providers, such as Stripe and Paystack (read only; card brand and last 4 digits only) - `1snag:enrichment:run` (write): Find and verify leads' work emails with your own connected data providers (spends your provider credits, within the caps you set; shows an estimate first) - `1snag:signals:manage` (write): Set up signal watches (Hacker News phrases, GitHub repositories) and recurring lead searches within the unit ceilings you confirm - `1snag:signals:ingest` (write): Report what your product's own users do (signed up, hit a limit, invited a teammate) so 1Snag can score them (for your product's server, not an assistant) - `1snag:assets:request` (write): Ask your connected Sigmora account for a campaign video, shorts, an ad image or copy (spends your Sigmora credits; shows the brief and price first and runs only after you confirm) - `1snag:webhooks:subscribe` (write): Have events you can already read sent at once to a Zapier or Make hook (instant triggers) - `1snag:social:draft` (write): Draft LinkedIn and X posts into the approval queue and add people to the daily "send it yourself" list (a person approves and publishes every post and sends every message by hand) ## Conventions - Idempotency: every create or spend takes an `Idempotency-Key` header (1 to 200 printable characters). Retry with the same key and body after a timeout or a 5xx; the same key with a different body is `409`. `POST /interactions` takes `idempotency_key` in the body. - Revisions: reads return `ETag: "rev-"`; updates need `If-Match` with it. A stale revision is `412`: re-read, then decide again. - Pagination: lists take `limit` and `cursor` and return the next cursor (`pagination.cursor`, or `next_cursor` on feeds). Cursors are opaque and bound to the workspace and the list. Each list states its maximum `limit` in the OpenAPI document. - Errors: `{ "error": { "code", "message", "details"?, "requestId" } }`. `402 QUOTA_EXCEEDED` means an allowance is used up: stop and tell a person, do not retry. `429 RATE_LIMIT_EXCEEDED` carries `Retry-After` (seconds). `503` with a `*_DISABLED` code means a feature is switched off. - Contact: nothing reaches a lead without consent, suppression, quiet-hour and policy checks; a held send says why (`GET /policy/reasons`). ## Limits - 100 requests a minute per workspace, across all its API keys and MCP connections (a workspace may have its own limit). People using the dashboard have their own allowance and do not spend this one. - 60 API-key lookups a minute per client IP for keys not recently seen (wrong or new keys); a valid key is then cached. - Request bodies up to 5 MiB; asset uploads up to 16 MiB. - 20 feedback items a day per workspace. - Plan allowances (email, AI calls, WhatsApp, seats) and the monthly AI cap: `GET /usage/summary`. ## Webhooks Up to 10 HTTPS endpoints per workspace, registered by a person in the dashboard. Each delivery is a POST with `X-1Snag-Event`, `X-1Snag-Event-Id`, `X-1Snag-Timestamp` and `X-1Snag-Signature: v1=` over `.` with the endpoint's `whsec_` secret. Delivery is at least once: deduplicate on the event id. Failed deliveries are retried up to 8 times over about 45 hours.