HTTP API for your agent

Agent API

You decide and approve. SimpL queues and guards. The human's Chrome extension executes on LinkedIn.

Base
https://api.simpl.sucks/api/agent/v1
Auth
Authorization: Bearer sk_agent_...
OpenAPI
https://api.simpl.sucks/api/agent/v1/openapi.json
Manifest
https://api.simpl.sucks/api/agent/v1/.well-known/simpl-agent.json

Start here

SimpL works with your own AI agent: it reads what SimpL found for you and what waits for your approval, and acts only when you say so. It needs an agent that can call web APIs, such as Claude Code, Cursor, n8n or Make. A plain chat in ChatGPT or Claude cannot reach SimpL.

  1. Let the agent connect: give your agent this page. It shows you a link and a code; open the link, sign in to SimpL, check the code and approve.
  2. Or make a key yourself: in SimpL, Settings → Integrations → Agent API → Create a key. Copy the text shown under the key and paste it into your agent.

Each agent gets its own key. Revoke one any time in Settings → Integrations; it stops at once.

Copy & run

Ready for agents and terminals. Paste the prompt into your agent, or curl the loop.

Agent prompt

Paste into Cursor / Claude / your agent

You are my sales agent. Use only the SimpL Agent API.

Base: https://api.simpl.sucks/api/agent/v1
Auth: Authorization: Bearer sk_agent_...
Docs: https://www.simplsales.ai/llms-agent-api.txt
OpenAPI: https://api.simpl.sucks/api/agent/v1/openapi.json
Manifest: https://api.simpl.sucks/api/agent/v1/.well-known/simpl-agent.json

You decide and approve. SimpL queues and guards. The human's Chrome extension executes on LinkedIn.

1. If I give you a key, use it. If I already have SimpL but no key: POST /oauth/device, show me verification_uri_complete and the code, poll POST /oauth/device/token until api_key.
2. If I am new: POST /access-requests with a full onboarding packet, poll ~once/minute, then claim.
3. Tell me to open Integrations and install the Chrome extension until GET /readiness ready=true.
4. Daily loop: GET /board first, then filtered opportunities + triage + drafts. Tell me what waits, including the questions SimpL asks me. Never download thousands of rows.
5. Ask me before you approve, edit or reject anything. Never claim a LinkedIn send happened without readiness + extension execution.

Full plain docs

Same body as /llms-agent-api.txt

# SimpL Agent API — plain text for agents

You decide and approve. SimpL queues and guards. The human's Chrome extension executes on LinkedIn.

Base: https://api.simpl.sucks/api/agent/v1
Auth: Authorization: Bearer sk_agent_...
OpenAPI: https://api.simpl.sucks/api/agent/v1/openapi.json
Manifest: https://api.simpl.sucks/api/agent/v1/.well-known/simpl-agent.json
Human setup: https://sales.thesimplplatform.io/?appTab=profile&tab=integrations
Chrome extension: https://chromewebstore.google.com/detail/simpl/noigjbkhonhmbhfbpghgjlfpieefjldh
HTML docs: https://www.simplsales.ai/docs/agents

## Start here (for the person)

SimpL works with your own AI agent: it reads what SimpL found for you and what waits for your approval, and acts only when you say so.
It needs an agent that can call web APIs, such as Claude Code, Cursor, n8n or Make. A plain chat in ChatGPT or Claude cannot reach SimpL.

1. Let the agent connect: give your agent this page. It shows you a link and a code; open the link, sign in to SimpL, check the code and approve.
2. Or make a key yourself: in SimpL, Settings → Integrations → Agent API → Create a key. Copy the text shown under the key and paste it into your agent.

Each agent gets its own key. Revoke one any time in Settings → Integrations; it stops at once.

## Connect an existing account

Preferred when the human already has SimpL. Do not POST /access-requests for existing accounts.

1. POST /oauth/device with { client_name, label }
2. Open verification_uri_complete for the human (or tell them to open it)
3. They log in and click Allow
4. Poll POST /oauth/device/token with { device_code } until api_key

  POST /oauth/device
  POST /oauth/device/token

- Or the human makes a key in Settings → Integrations → Agent API and pastes it to you, with a ready-made prompt
- Store the key once — it is not shown again

## Onboard a new account

Use only when the human does not have SimpL yet. Send a full onboarding packet — not just name and email.

1. POST /access-requests with email, full_name, company_name, product_offer, value_proposition, icp_brief, industries[], geographies[], size_min, size_max, target_roles[], signals[], example_outreach_messages[], decision_maker_guidance, outreach_context
2. Poll GET /access-requests/{id} about once per minute (poll_after_seconds ≈ 60). Expect up to ~15 minutes
3. On approved: POST /access-requests/{id}/claim with claim_token → api_key (once)
4. Meanwhile tell the human: accept the invite email, open Integrations, install the Chrome extension, stay logged into LinkedIn

  POST /access-requests
  GET /access-requests/{id}
  POST /access-requests/{id}/claim

## Readiness gate

Mandatory before approving LinkedIn drafts. You approve; the extension sends.

  GET /readiness
  GET /readiness?wait_seconds=60

- If ready is false, do not approve LinkedIn drafts
- POST /drafts/{id}/approve returns 409 linkedin_not_ready with blockers and agent_instructions
- Relay message_for_user to your human, then wait with wait_seconds=60 (held open until ready, max 90s)
- Blocking: extension_not_seen, extension_access_disabled, linkedin_url_missing, user_on_vacation
- Informational: outside_active_hours (07:00–19:00 UTC), daily_limit_reached, linkedin_sync_stale

## Day board

Totals only — opportunities by row type, drafts by channel, activity by status, limits. Call this before paging lists.

  GET /board
  GET /me

- If ready=false, coach Integrations (blockers[].action_url) — do not deep-page the backlog
- No item bodies on the board

## Daily loop

Page filtered slices only. returned/count is the page; summary/total is the corpus.

  POST /icp/preview · POST /icp · PATCH /icp/{id}
  POST /opportunities/refresh · GET /opportunities
  POST /opportunities/{company_id}/claim|monitor|not-in-target
  GET /drafts · GET /drafts/{id}
  PATCH /drafts/{id} · POST /drafts/{id}/regenerate
  POST /drafts/{id}/approve|reject
  GET /activity

- Filter lists with message_type, channel, newer_than_days, row_type, status
- Every draft has kind: message (yours to approve), calendar_invite (approved on its card in the app) or question (SimpL asks the human: read question.text and question.options and tell them; they answer in the app — approve/reject answer 409 answer_in_app, bulk lists them under questions)
- Drafts and activity say who and where: lead_name, lead_job_title, lead_linkedin_url, company_name, company_website, company_linkedin_url, stage. No contact details beyond LinkedIn
- GET /activity and the board's activity totals cover the last 90 days; older history is not available through the API
- Default draft list uses message_preview; prefer GET /drafts/{id} for one review
- Draft status: PENDING_APPROVAL → approve → PENDING → extension RUNNING → COMPLETED/FAILED
- Pass include_summary=false on follow-up pages — the summary aggregate is the slow part

## Bulk draft actions

One call per draft does not scale. Use bulk endpoints with explicit ids and/or filters.

  POST /drafts/bulk-approve
  POST /drafts/bulk-reject

- Filters: channel, message_type, newer_than_days, older_than_days; max_items default 50, hard cap 200
- A call with neither ids nor filters returns 400 unfiltered_bulk
- Run dry_run: true first on a broad filter
- Retries are safe — only PENDING_APPROVAL rows move
- Keep calling while remaining_after_call > 0
- bulk-approve enforces the same readiness gate as single approve

## Limits and ownership

Rate limits and human key control.

- 120 requests per 60s per key — 429 carries Retry-After and retry_after_seconds
- If you are hitting the limit, use bulk endpoints, include_summary=false, and filtered pages
- Keys expire 365 days after issue unless revoked earlier
- Humans list and revoke keys in Settings → Integrations — revocation is immediate
- OpenAPI is the source of truth for request bodies

## Do not

- Do not claim LinkedIn sends without GET /readiness ready=true — you approve, the extension executes
- Do not POST /access-requests for humans who already have SimpL — use device OAuth
- Do not download thousands of drafts — filter and page
- Do not run unfiltered bulk actions
- Do not use internal service tokens — only sk_agent_ keys

Scopes: icp:write, opportunities:read, pipeline:write, drafts:read, drafts:approve, activity:read
Rate limit: 120 requests per 60s per key
Keys expire 365 days after issue unless revoked earlier

Contract: You decide and approve. SimpL queues. The extension sends.

Connect (curl)

Existing SimpL account → API key

# 1) Start device OAuth
curl -sS -X POST https://api.simpl.sucks/api/agent/v1/oauth/device \
  -H 'content-type: application/json' \
  -d '{"client_name":"my-agent","label":"local"}'

# 2) Open verification_uri_complete in the browser, click Allow

# 3) Poll for the key (repeat until api_key)
curl -sS -X POST https://api.simpl.sucks/api/agent/v1/oauth/device/token \
  -H 'content-type: application/json' \
  -d '{"device_code":"DEVICE_CODE_FROM_STEP_1"}'

Day loop (curl)

board → readiness → drafts

export SIMPL_AGENT_API_KEY='sk_agent_...'

# Day totals (call this first)
curl -sS https://api.simpl.sucks/api/agent/v1/board \
  -H "authorization: Bearer $SIMPL_AGENT_API_KEY"

# Readiness (long-poll up to ~60s)
curl -sS 'https://api.simpl.sucks/api/agent/v1/readiness?wait_seconds=60' \
  -H "authorization: Bearer $SIMPL_AGENT_API_KEY"

# Recent drafts to review
curl -sS 'https://api.simpl.sucks/api/agent/v1/drafts?message_type=response&newer_than_days=30&limit=25' \
  -H "authorization: Bearer $SIMPL_AGENT_API_KEY"

Connect an existing account

Preferred when the human already has SimpL. Do not POST /access-requests for existing accounts.

  1. POST /oauth/device with { client_name, label }
  2. Open verification_uri_complete for the human (or tell them to open it)
  3. They log in and click Allow
  4. Poll POST /oauth/device/token with { device_code } until api_key
  • POST /oauth/device
  • POST /oauth/device/token
  • Or the human makes a key in Settings → Integrations → Agent API and pastes it to you, with a ready-made prompt
  • Store the key once — it is not shown again

Onboard a new account

Use only when the human does not have SimpL yet. Send a full onboarding packet — not just name and email.

  1. POST /access-requests with email, full_name, company_name, product_offer, value_proposition, icp_brief, industries[], geographies[], size_min, size_max, target_roles[], signals[], example_outreach_messages[], decision_maker_guidance, outreach_context
  2. Poll GET /access-requests/{id} about once per minute (poll_after_seconds ≈ 60). Expect up to ~15 minutes
  3. On approved: POST /access-requests/{id}/claim with claim_token → api_key (once)
  4. Meanwhile tell the human: accept the invite email, open Integrations, install the Chrome extension, stay logged into LinkedIn
  • POST /access-requests
  • GET /access-requests/{id}
  • POST /access-requests/{id}/claim

Readiness gate

Mandatory before approving LinkedIn drafts. You approve; the extension sends.

  • GET /readiness
  • GET /readiness?wait_seconds=60
  • If ready is false, do not approve LinkedIn drafts
  • POST /drafts/{id}/approve returns 409 linkedin_not_ready with blockers and agent_instructions
  • Relay message_for_user to your human, then wait with wait_seconds=60 (held open until ready, max 90s)
  • Blocking: extension_not_seen, extension_access_disabled, linkedin_url_missing, user_on_vacation
  • Informational: outside_active_hours (07:00–19:00 UTC), daily_limit_reached, linkedin_sync_stale

Day board

Totals only — opportunities by row type, drafts by channel, activity by status, limits. Call this before paging lists.

  • GET /board
  • GET /me
  • If ready=false, coach Integrations (blockers[].action_url) — do not deep-page the backlog
  • No item bodies on the board

Daily loop

Page filtered slices only. returned/count is the page; summary/total is the corpus.

  • POST /icp/preview · POST /icp · PATCH /icp/{id}
  • POST /opportunities/refresh · GET /opportunities
  • POST /opportunities/{company_id}/claim|monitor|not-in-target
  • GET /drafts · GET /drafts/{id}
  • PATCH /drafts/{id} · POST /drafts/{id}/regenerate
  • POST /drafts/{id}/approve|reject
  • GET /activity
  • Filter lists with message_type, channel, newer_than_days, row_type, status
  • Every draft has kind: message (yours to approve), calendar_invite (approved on its card in the app) or question (SimpL asks the human: read question.text and question.options and tell them; they answer in the app — approve/reject answer 409 answer_in_app, bulk lists them under questions)
  • Drafts and activity say who and where: lead_name, lead_job_title, lead_linkedin_url, company_name, company_website, company_linkedin_url, stage. No contact details beyond LinkedIn
  • GET /activity and the board's activity totals cover the last 90 days; older history is not available through the API
  • Default draft list uses message_preview; prefer GET /drafts/{id} for one review
  • Draft status: PENDING_APPROVAL → approve → PENDING → extension RUNNING → COMPLETED/FAILED
  • Pass include_summary=false on follow-up pages — the summary aggregate is the slow part

Bulk draft actions

One call per draft does not scale. Use bulk endpoints with explicit ids and/or filters.

  • POST /drafts/bulk-approve
  • POST /drafts/bulk-reject
  • Filters: channel, message_type, newer_than_days, older_than_days; max_items default 50, hard cap 200
  • A call with neither ids nor filters returns 400 unfiltered_bulk
  • Run dry_run: true first on a broad filter
  • Retries are safe — only PENDING_APPROVAL rows move
  • Keep calling while remaining_after_call > 0
  • bulk-approve enforces the same readiness gate as single approve

Limits and ownership

Rate limits and human key control.

  • 120 requests per 60s per key — 429 carries Retry-After and retry_after_seconds
  • If you are hitting the limit, use bulk endpoints, include_summary=false, and filtered pages
  • Keys expire 365 days after issue unless revoked earlier
  • Humans list and revoke keys in Settings → Integrations — revocation is immediate
  • OpenAPI is the source of truth for request bodies

Do not

  • Do not claim LinkedIn sends without GET /readiness ready=true — you approve, the extension executes
  • Do not POST /access-requests for humans who already have SimpL — use device OAuth
  • Do not download thousands of drafts — filter and page
  • Do not run unfiltered bulk actions
  • Do not use internal service tokens — only sk_agent_ keys

Your next sales conversation starts here.

Bring the software into your sales team. Keep control of your strategy and customer relationships. Pay only for qualified meetings held.

Write an email