Zevari API Playbooks

Where This Sits

API Playbooks is the call-order guide for developers, scheduled runners, CRM integrations, internal tools, and AI agents using the public REST API. Use the API Reference for endpoint schemas. Use MCP Reference for MCP tool semantics. Use Help Workflows for human-facing Zevari workflow concepts.

Operating Principles

• Use the playbooks for order of operations

  The API reference tells you the exact schema for one endpoint. API Playbooks tell you which endpoint to call first, which response fields to preserve, and what to do next.

• Treat the API key as the active context

  A Zevari API key is bound to an organization and active LinkedIn sender. Do not invent workspace, account, or sender IDs that are not returned by Zevari.

• Stop at approval boundaries

  LinkedIn sends, public posts, campaign activation, and other sensitive writes require confirmations.requestAction before the write endpoint executes.

• Read safety before scheduling writes

  Call safety.getStatus before queued LinkedIn work. If safetyPaused is true, hold or route work according to the pause fields instead of firing into a blocked sender.

• Preserve request IDs and docs URLs

  Every API error includes request_id plus error docs and suggested action fields. Preserve those values in logs and support handoffs.

Confirmation Action Types

When staging a confirmation, use the action_type that matches the endpoint you will execute after approval.

• linkedin.sendConnectionRequest

  Use confirmations.requestAction with action_type linkedin_send_connection_request before executing linkedin.sendConnectionRequest.

• linkedin.sendMessage

  Use confirmations.requestAction with action_type linkedin_send_message before executing linkedin.sendMessage.

• linkedin.sendInMail

  Use confirmations.requestAction with action_type linkedin_send_inmail before executing linkedin.sendInMail.

• linkedin.createPost

  Use confirmations.requestAction with action_type linkedin_create_post before executing linkedin.createPost.

• linkedin.commentOnPost

  Use confirmations.requestAction with action_type linkedin_comment_on_post before executing linkedin.commentOnPost.

• linkedin.reactToPost

  Use confirmations.requestAction with action_type linkedin_react_to_post before executing linkedin.reactToPost.

• campaigns.updateStatus status=active

  Use confirmations.requestAction with action_type campaign_activate before executing campaigns.updateStatus status=active.

Bootstrap an API Runner

Discover the public API surface, verify the API key context, and check LinkedIn safety before planning work. Methods: GET /v1/methods, profile.get, safety.getStatus, libraryContext.get.

• 1. List the public methods

  Fetch /v1/methods at startup or during tool discovery. Use the returned method names, paths, summaries, and docs URLs as the source of truth. Example: curl -sS https://api.zevari.ai/v1/methods \ -H "Authorization: Bearer $ZEVARI_API_KEY"

• 2. Read the business profile

  Call profile.get to understand the workspace voice, company context, ICP, and defaults before generating copy or scoring leads. Example: curl -sS -X POST https://api.zevari.ai/v1/profile/get \ -H "Authorization: Bearer $ZEVARI_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'

• 3. Check LinkedIn safety

  Call safety.getStatus before queueing LinkedIn writes. If safetyPaused is true, do not call send endpoints until the status says active or the response provides an auto-resume timestamp you can schedule around. Example: curl -sS -X POST https://api.zevari.ai/v1/safety/getStatus \ -H "Authorization: Bearer $ZEVARI_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'

• 4. Load Library context only when generation needs it

  Call libraryContext.get before generating outreach, campaign copy, or content that should reflect saved templates and brand context.

• Note 1

  Use OpenAPI for exact schemas; use this playbook to decide call order.

• Note 2

  API runners should cache method discovery briefly but refresh after deployment or schema errors.

Run an Approval-Gated LinkedIn Write

Stage the exact write payload, wait for approval or Autopilot, then execute the write endpoint with the returned confirmation_id. Methods: confirmations.requestAction, linkedin.sendConnectionRequest, linkedin.sendMessage, linkedin.sendInMail, linkedin.createPost, linkedin.commentOnPost, linkedin.reactToPost.

• 1. Build the exact executable payload

  Use the target write endpoint's exact field names. For example, connection requests use identifier and optional note; messages use chatId or recipientId plus message.

• 2. Apply sender-tier note limits before staging

  For linkedin_send_connection_request, cap note to the active sender's LinkedIn tier before calling confirmations.requestAction: free senders support 200 characters; premium and sales_navigator senders support 300. If you exceed the active sender's limit, staging or execution returns HTTP 400 with ok=false and data.error='connection_note_too_long'. Treat that as a payload error, shorten the note, and stage a new confirmation.

• 3. Stage confirmation

  Call confirmations.requestAction with the action_type that matches the write endpoint and the exact payload you intend to execute. Example: curl -sS -X POST https://api.zevari.ai/v1/confirmations/requestAction \ -H "Authorization: Bearer $ZEVARI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action_type": "linkedin_send_connection_request", "payload": { "identifier": "ACoAAAexample", "note": "Saw your post on AI workflow ops. Open to connecting?" } }'

• 4. Branch on Autopilot

  If data.autopilot.approved is true, immediately call the write endpoint with data.confirmation_id. If not, store data.approval_url, show it to the user, and wait until they approve in Zevari.

• 5. Execute with confirmation_id

  Retry the original write endpoint with the approved confirmation_id. Do not edit the payload between confirmation and execution. Example: curl -sS -X POST https://api.zevari.ai/v1/linkedin/sendConnectionRequest \ -H "Authorization: Bearer $ZEVARI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "identifier": "ACoAAAexample", "note": "Saw your post on AI workflow ops. Open to connecting?", "confirmation_id": "pac_..." }'

• 6. Handle drift or expiry

  If execution fails because the confirmation is expired, stale, rejected, or payload-drifted, stage a new confirmation with the current exact payload.

• Note 1

  REST clients should not use MCP-only chat approval tools.

• Note 2

  Do not reuse a confirmation_id after changing an over-limit connection note; stage a fresh confirmation with the shortened note.

• Note 3

  For two or more outbound LinkedIn writes in one planned batch, use the bulk-confirmation pattern when available instead of staging separate approval URLs.

Create and Launch a Campaign

Create a draft campaign, stage campaign activation approval, then activate the campaign with the approved confirmation. Methods: campaigns.create, campaigns.validate, confirmations.requestAction, campaigns.updateStatus, campaigns.getProgress.

• 1. Create the campaign as a draft

  Call campaigns.create with targets, step configuration, and generated content. Campaign creation persists the plan; it does not launch sending by itself.

• 2. Validate before launch

  Call campaigns.validate or inspect the creation response for missing targets, unsafe step configuration, unsupported action types, or sender readiness issues.

• 3. Stage activation approval

  Campaign activation is approval-gated. Stage a confirmation with action_type campaign_activate and payload containing the campaign_id. Example: curl -sS -X POST https://api.zevari.ai/v1/confirmations/requestAction \ -H "Authorization: Bearer $ZEVARI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "action_type": "campaign_activate", "payload": { "campaign_id": "campaign_..." } }'

• 4. Activate after approval

  When Autopilot approves or the user approves in the browser, call campaigns.updateStatus with status active and the same confirmation_id. Example: curl -sS -X POST https://api.zevari.ai/v1/campaigns/updateStatus \ -H "Authorization: Bearer $ZEVARI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "campaign_id": "campaign_...", "status": "active", "confirmation_id": "pac_..." }'

• 5. Monitor progress

  Call campaigns.getProgress for counts, target states, blocked conditions, and recent execution outcomes. If safety pauses the sender, hold new activation and scheduling work until safety clears.

Search LinkedIn and Save Targets

Page through LinkedIn search results, normalize prospects, save targets, and optionally attach them to a campaign. Methods: linkedin.searchProfiles, targets.save, targets.createList, campaigns.addTargets.

• 1. Search with a stable query

  Call linkedin.searchProfiles with the query, filters, and limit. Keep the same request body while paging. Example: curl -sS -X POST https://api.zevari.ai/v1/linkedin/searchProfiles \ -H "Authorization: Bearer $ZEVARI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "founder AI agency", "job_titles": ["Founder"], "locations": ["United States"], "limit": 50 }'

• 2. Use next_cursor for pagination

  If data.has_more is true and data.next_cursor is present, repeat the same search body with cursor set to that value. Stop when has_more is false.

• 3. Save usable targets

  Call targets.save or targets.createList with the profiles you actually want to pursue. Keep provider IDs and LinkedIn URLs from the search result; do not synthesize them.

• 4. Add targets to a campaign when ready

  Call campaigns.addTargets only after the campaign exists and the target list has been reviewed or filtered. Use campaigns.validate before activation.

• Note 1

  Search endpoints are provider-backed and safety-scoped. Respect rate-limit and safety responses instead of looping aggressively.

• Note 2

  Cursors are opaque. Do not parse or alter them.

Triage Inbox and Send a Reply

Read inbox context, classify or research the sender, generate a reply, stage approval, then send the message. Methods: linkedin.getInbox, linkedin.getMessages, agents.researchPerson, agents.generateMessages, confirmations.requestAction, linkedin.sendMessage.

• 1. List inbox threads

  Call linkedin.getInbox to find the active thread or lead conversation. Store the chatId returned by Zevari.

• 2. Read message history

  Call linkedin.getMessages with the chatId before drafting a reply. Do not reply from stale or partial context.

• 3. Research and draft

  Use agents.researchPerson, agents.behavioralProfile, or agents.generateMessages when the reply needs personalization. The output is a draft, not permission to send.

• 4. Stage and execute

  Call confirmations.requestAction with action_type linkedin_send_message and payload containing chatId and message. After approval, call linkedin.sendMessage with the same chatId, message, and confirmation_id.

• 5. Protect against stale replies

  If you track expected_last_inbound_at, include it so Zevari can block replies when the lead has responded since the draft was prepared.

Save, Review, and Publish Content

Create content drafts through the API, keep publishing approval-gated, and use LinkedIn content endpoints only after confirmation. Methods: content.save, content.list, content.update, confirmations.requestAction, linkedin.createPost, linkedin.reactToPost, linkedin.commentOnPost.

• 1. Save draft content

  Call content.save for drafts and content.update for revisions. Saving internal content is not the same as publishing to LinkedIn.

• 2. Stage LinkedIn publishing separately

  When a public LinkedIn post is ready, stage a confirmation with action_type linkedin_create_post and payload containing the exact post content.

• 3. Publish with confirmation_id

  Call linkedin.createPost only after approval. Preserve confirmation_id and the exact approved content.

• 4. Engage with existing posts carefully

  For comments and reactions, stage linkedin_comment_on_post or linkedin_react_to_post first. Use provider post IDs returned by Zevari or LinkedIn search/read endpoints.

Handle Safety Pauses and Circuit Breakers

Use safety.getStatus to decide whether to wait, retry, contact support, or remove a sender from rotation. Methods: safety.getStatus, linkedin.getSafetyStatus.

• 1. Read status before queued sends

  Call safety.getStatus for the active API key context before releasing queued LinkedIn outreach.

• 2. Pause on currentStatus

  If currentStatus is paused_circuit_breaker or safetyPaused is true, stop LinkedIn writes for that sender. Do not keep retrying failed sends.

• 3. Schedule from absolute time

  If autoResumes is true and resumesAt or cooldownEndsAt is present, hold queued work until that ISO timestamp, then refresh status before releasing the queue.

• 4. Use diagnostic fields for support

  Capture pauseReasonDetail, triggeringActionType, failureCount, failureThreshold, upstreamErrorCodes, and requestIds. Include those in support handoffs.

• 5. Do not automate manual resume

  If autoResumes is false or resumesAt is null, follow resolutionHint. Public REST does not expose linkedin.resumeAll because it mutates account-wide safety state.

Handle API Errors

Preserve Zevari's structured error envelope and recover by reading docs_url and suggested_action before retrying. Methods: All methods.

• 1. Log the whole envelope

  Store request_id, error.code, error.message, error.docs_url, error.suggested_action, method, and any validation details.

• 2. Use HTTP status for transport, error.code for behavior

  A 401 means API key/auth context. A 400 may be invalid arguments, missing confirmation, payload drift, or safety denial. A 429 means rate limiting. The error.code and suggested_action tell you what to do next.

• 3. Retry only after correcting the cause

  Do not blindly retry confirmation errors, safety pauses, invalid arguments, unsupported methods, or stale approvals. Read docs_url and rebuild the request if necessary.

• 4. Escalate with request_id

  When contacting Zevari support, include request_id, endpoint path, method, timestamp, active workspace/sender if known, and the exact error fields.

Docs Links

• Help Center

  Human-facing guide to Zevari skills, workflows, agents, videos, safety, and support.

• Workflow Guide

  LinkedIn outreach, content, prospect research, audience analysis, campaign, inbox, and GTM workflows for Claude.

• Prompting Guide

  Copy-ready prompts that require AI assistants to read the MCP reference before acting.

• Workspaces and Sender Seats

  Human-facing setup guide for workspaces, members, billing, add-on LinkedIn sender seats, and teammate LinkedIn connections.

• Safety Center

  Human-facing guide to Zevari safety guardrails, warm-up, pauses, blocked actions, and recovery state.

• Warm-Up

  Human-facing guide to LinkedIn sender warm-up and gradual activity ramping.

• API Playbooks

  Ordered REST call flows for developers and AI agents using the Zevari API.

• MCP Reference

  Agent-facing tool schemas, capability contracts, examples, gotchas, and recovery guidance.

• API Reference

  Public REST API reference powered by the Zevari OpenAPI document.

• MCP Reference JSON

  Machine-readable MCP tool reference.

• LLMs Full

  AI-readable Zevari documentation bundle.

• Support

  Send bug reports, support handoffs, and feature requests.