SalesOS

Agents

AI agent management and execution

List all registered agents with their status

GET
/v1/agents

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/agents" \
  -H "Authorization: Bearer <token>"

List of agents

Manually trigger an agent execution

POST
/v1/agents/trigger

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
agentTypeRequiredstring

Type of agent to trigger

Value in: "DEAL_HEALTH" | "PIPELINE_ACCELERATION" | "ACCOUNT_INTELLIGENCE" | "OUTREACH_OPTIMIZATION" | "MEETING_PREP" | "COACHING" | "COMPETITIVE_INTELLIGENCE" | "NEXT_BEST_ACTION" | "WIN_CYCLE_ANALYZER" | "DATA_ENRICHMENT" | "WORKFLOW_AUTOMATION" | "LISTENING" | "REASONING" | "LEARN_MORE" | "EMAIL_ACTION" | "CRM_ACTION" | "MEETING_ACTION"
entityTypestring

Entity type to target (Lead, Opportunity, Account, etc.)

entityIdstring

Entity ID to target

prioritystring

Execution priority

Value in: "LOW" | "MEDIUM" | "HIGH" | "URGENT"
metadataobject

Additional metadata for the agent

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/agents/trigger" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentType": "DEAL_HEALTH",
    "entityType": "string",
    "entityId": "string",
    "priority": "LOW",
    "metadata": {}
  }'

Agent triggered

Whether agents run for the caller's organization

GET
/v1/agents/org-settings

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/agents/org-settings" \
  -H "Authorization: Bearer <token>"

Turn agents on or off for one organization (org OWNER/ADMIN for their own org, system ADMIN for any)

PATCH
/v1/agents/org-settings

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
agentsEnabledRequiredboolean

Whether agents may run for the organization

organizationIdstring

Target organization (system ADMIN only; defaults to the session org)

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X PATCH "https://api.salesos.org/v1/agents/org-settings" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentsEnabled": true,
    "organizationId": "string"
  }'

Get current queue status

GET
/v1/agents/queue/status

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/agents/queue/status" \
  -H "Authorization: Bearer <token>"

Queue status

Get pending alerts count by priority

GET
/v1/agents/alerts/pending

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/agents/alerts/pending" \
  -H "Authorization: Bearer <token>"

Pending alerts summary

Get alerts for the current user

GET
/v1/agents/alerts

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Query Parameters

agentTypestring

Filter by agent type

Value in: "DEAL_HEALTH" | "PIPELINE_ACCELERATION" | "ACCOUNT_INTELLIGENCE" | "OUTREACH_OPTIMIZATION" | "MEETING_PREP" | "COACHING" | "COMPETITIVE_INTELLIGENCE" | "NEXT_BEST_ACTION" | "WIN_CYCLE_ANALYZER" | "DATA_ENRICHMENT" | "WORKFLOW_AUTOMATION" | "LISTENING" | "REASONING" | "LEARN_MORE" | "EMAIL_ACTION" | "CRM_ACTION" | "MEETING_ACTION"
statusstring
Value in: "PENDING" | "ACKNOWLEDGED" | "ACTIONED" | "DISMISSED" | "EXPIRED"
prioritystring
Value in: "LOW" | "MEDIUM" | "HIGH" | "URGENT"
entityTypestring

Entity type filter

entityIdstring

Entity ID filter

daysnumber

Number of days to look back

Default: 7
limitnumber

Max results

Default: 50
curl -X GET "https://api.salesos.org/v1/agents/alerts?agentType=DEAL_HEALTH&status=PENDING&priority=LOW&entityType=%3Cstring%3E&entityId=%3Cstring%3E&days=7&limit=50" \
  -H "Authorization: Bearer <token>"

List of alerts

Update alert status (acknowledge, action, dismiss)

PATCH
/v1/agents/alerts/{alertId}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
statusRequiredstring

New alert status

Value in: "ACKNOWLEDGED" | "ACTIONED" | "DISMISSED"
notesstring

Notes about the action taken

Path Parameters

alertIdRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X PATCH "https://api.salesos.org/v1/agents/alerts/<string>" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "ACKNOWLEDGED",
    "notes": "string"
  }'

Alert updated

Delete an alert

DELETE
/v1/agents/alerts/{alertId}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

alertIdRequiredstring
curl -X DELETE "https://api.salesos.org/v1/agents/alerts/<string>" \
  -H "Authorization: Bearer <token>"

Alert deleted

Agent-proposed actions for the caller's org

GET
/v1/agents/actions

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Query Parameters

statusstring
Value in: "PENDING_APPROVAL" | "APPROVED" | "REJECTED" | "EXECUTING" | "COMPLETED" | "FAILED"
actionTypestring

Action type filter

daysnumber

Number of days to look back

Default: 7
limitnumber

Max results

Default: 50
curl -X GET "https://api.salesos.org/v1/agents/actions?status=PENDING_APPROVAL&actionType=%3Cstring%3E&days=7&limit=50" \
  -H "Authorization: Bearer <token>"

List of actions

Action counts by status for the caller's org (30d)

GET
/v1/agents/actions/summary

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/agents/actions/summary" \
  -H "Authorization: Bearer <token>"

{}

Approve (and execute) or reject a pending action

PATCH
/v1/agents/actions/{actionId}/approve

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
approvedRequiredboolean

Whether to approve or reject the action

rejectionReasonstring

Reason for rejection (if rejected)

Path Parameters

actionIdRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X PATCH "https://api.salesos.org/v1/agents/actions/<string>/approve" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "approved": true,
    "rejectionReason": "string"
  }'

Action updated

Re-run a failed action

POST
/v1/agents/actions/{actionId}/retry

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

actionIdRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/agents/actions/<string>/retry" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

{}

Get agent execution history

GET
/v1/agents/executions

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Query Parameters

agentTypestring
Value in: "DEAL_HEALTH" | "PIPELINE_ACCELERATION" | "ACCOUNT_INTELLIGENCE" | "OUTREACH_OPTIMIZATION" | "MEETING_PREP" | "COACHING" | "COMPETITIVE_INTELLIGENCE" | "NEXT_BEST_ACTION" | "WIN_CYCLE_ANALYZER" | "DATA_ENRICHMENT" | "WORKFLOW_AUTOMATION" | "LISTENING" | "REASONING" | "LEARN_MORE" | "EMAIL_ACTION" | "CRM_ACTION" | "MEETING_ACTION"
statusstring
Value in: "PENDING" | "RUNNING" | "COMPLETED" | "FAILED" | "CANCELLED" | "RATE_LIMITED"
daysnumber

Number of days to look back

Default: 7
limitnumber

Max results

Default: 50
curl -X GET "https://api.salesos.org/v1/agents/executions?agentType=DEAL_HEALTH&status=PENDING&days=7&limit=50" \
  -H "Authorization: Bearer <token>"

Execution history

Get details of a specific execution

GET
/v1/agents/executions/{executionId}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

executionIdRequiredstring
curl -X GET "https://api.salesos.org/v1/agents/executions/<string>" \
  -H "Authorization: Bearer <token>"

Execution details

Get status of a specific agent

GET
/v1/agents/{agentType}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

agentTypeRequiredstring
curl -X GET "https://api.salesos.org/v1/agents/<string>" \
  -H "Authorization: Bearer <token>"

Agent status

A I

AI assistant and natural language queries

Agent Marketplace

Pre-built AI agent library