Developer API and CLI are live for agent-native workflows

FirstSales now has a public developer surface: a scoped Developer API, an agent-friendly CLI, production API-key management, API usage logs, and published docs at https://developer.firstsales.io. This release is for teams that want FirstSales to be controlled by Codex, Claude Code, Gemini, Claude.ai, CI jobs, internal scripts, or their own operating dashboards without depending on app-private browser routes.

Until now, the web app was the primary control surface. That works for humans, but it is awkward for agents. Agents need stable JSON, scoped credentials, predictable errors, idempotent writes, and a way to verify what changed after an action. The new /api/v1 contract and firstsales CLI give them that surface.

New

Developer API and CLI are live for agent-native workflows

What shipped

You can now open Settings -> API and create multiple Developer API keys for an organization. Each key has a name, a prefix shown in the table, and explicit scopes such as organizations:read, workspaces:read, campaigns:read, campaigns:write, contacts:read, contacts:write, inbox:read, inbox:write, connectors:read, kb:read, offerings:write, billing:read, members:read, groups:write, domains:read, and api_keys:write. The raw secret is shown only once at creation. After that, the app only stores and displays safe metadata, so a teammate or agent can identify which key was used without exposing the credential itself.

The first public API version is also live under /api/v1. It includes identity, organization, workspace, campaign, contact, contact list, tag, import, export, inbox, connector, knowledge base, offering, tracking domain, billing, team, group, domain, and API-key operations. Campaign workflows can be inspected and updated through the public contract, campaign lifecycle actions can start, pause, and resume work, and status endpoints can be used to verify progress after a mutation.

The CLI package is published as @firstsales.io/cli v0.1.0 and installs the firstsales binary. It is intentionally thin: it maps commands to the Developer API, prints JSON by default, supports pretty output for humans, accepts flags or environment variables, and keeps business logic on the server. The initial command surface includes whoami, doctor, commands, orgs list, workspaces list, campaigns list/create/get/update/start/pause/resume/progress/analytics/events/sources/workflow/workflow-update, contacts list/create/get/update/delete, contact-lists, contact-tags, contact-imports, contact-exports, inbox threads/thread/reply/read/approve-draft/reject-draft, connectors list/delete/test, kb list/create/get/update/delete/query, offerings, tracking-domains, billing, members, invitations, groups, domains, and api-keys list/create/revoke.

New

Developer API and CLI are live for agent-native workflows

Built for agents, not just terminals

The CLI is useful in a shell, but the real design target is an AI operator loop. A coding agent can start with firstsales whoami to validate the key, run firstsales commands to discover supported actions, list organizations and workspaces, inspect a campaign, apply a scoped mutation, then re-read progress, logs, or analytics to verify the result. Mutating commands accept JSON bodies, JSON files, dry-run previews, and idempotency keys so retrying a step does not accidentally duplicate a contact import or repeat a lifecycle action.

For Codex and Claude Code, this means the agent can work directly from the repo, CI runner, or task pane. For Gemini and other automation, the stable JSON output and predictable exit codes make it possible to branch on success, validation errors, missing scopes, or unsupported operations. For Claude.ai or no-shell environments, the docs expose the same API contract with copyable request patterns, so the human can run a curl command or give the request to an integration service.

How to start

1. Open Settings -> API.
2. Create a key for the system that will use it, for example Production CI, Claude Code, or RevOps reporting.
3. Select only the scopes needed for that workflow. A reporting job can use read scopes; a campaign operator needs write scopes only for the resources it will change.
4. Copy the secret once and store it in the environment or secret manager used by the agent.
5. Install the CLI with npm install -g @firstsales.io/cli.
6. Set FIRSTSALES_API_KEY and, when useful, FIRSTSALES_BASE_URL, FIRSTSALES_ORG_ID, and FIRSTSALES_WORKSPACE_ID.
7. Run firstsales whoami --json and firstsales doctor --pretty before the first real action.
8. Use firstsales commands --pretty to inspect the full command list available to the installed version.

New

Developer API and CLI are live for agent-native workflows

Security model

This release was built with a fail-closed security model. API keys are scoped, organization-aware, and workspace-aware. Revoked keys fail immediately. Keys fail if the creator loses access. The UI shows prefixes, not secrets. The logs record request metadata such as route, method, status, latency, and request ID, but avoid raw secrets and raw request bodies. Destructive CLI actions require an explicit confirmation flag. Retryable mutations can carry idempotency keys. Unsupported public surfaces return structured unsupported_operation errors instead of silently falling back to private app routes.

API logs are part of the operating loop. If an agent reports that it changed a campaign, you can open Settings -> API -> Logs and filter by route, status code family, or request ID. That makes it possible to answer: which key made the call, did it succeed, how long did it take, and what should we inspect next?

Example workflows

A few concrete workflows are now possible without opening the browser. An agent can audit every active campaign, find the ones with zero recent sends, inspect the workflow, and report exactly which node is blocking progress. A RevOps script can import contacts from a daily partner feed using an idempotency key per row, then re-read the import status before handing the list to a campaign. A support teammate can test a connector, check inbox threads, or approve and reject drafts from a controlled terminal session. A finance report can pull billing credits, usage summaries, credit history, payments, and top-ups on a schedule.

The same pattern works for admin operations. Team owners can list members, manage invitations, create groups, update group permissions, add domains, revoke stale API keys, and verify tracking domains from the public API. Every write still goes through server-side authorization and scope checks, so using the CLI does not bypass the app's permissions model. It simply gives trusted automation a stable way to do the same work.

Version boundaries

This is v0.1.0 of the public developer platform, so we are keeping the contract explicit. Supported commands map to documented /api/v1 endpoints. App-private routes are not part of the CLI. Signals and webhooks intentionally return unsupported_operation until those surfaces are ready for public use. That boundary is important for agents because it prevents accidental dependence on a temporary internal route that could change without warning.

Why this matters

This turns FirstSales from a browser-only tool into an automatable sales operating system. A founder can ask an agent to list stalled campaigns. A RevOps engineer can script contact imports with idempotency. A support teammate can check connector health from a terminal. A CI job can verify that a workspace has the right tracking domains before a launch. A custom dashboard can pull billing usage, campaign progress, and inbox state without scraping the app.

The web app remains the best place for visual work and human review. The API and CLI now cover the repeatable work around it: inspect, mutate deliberately, verify, and log what happened.