POST /v1/actions

The core action proxy. Every call your agent makes to a connected SaaS platform flows through this endpoint.

Most agents call this indirectly via the MCP read_platform, write_platform and delete_platform tools. Direct invocation is only needed when building a custom MCP server or integrating from a non-MCP host.

Request

POST /v1/actions HTTP/1.1
Host: api.agentvalet.ai
Authorization: Bearer <agent-rs256-jwt>
Content-Type: application/json

{
  "platform": "slack",
  "endpoint": "/api/chat.postMessage",
  "method": "POST",
  "scope": "chat:write",
  "data": { "channel": "#general", "text": "Hello" },
  "headers": {},
  "reason": "Posting the daily standup summary"
}

Success — 2xx

The upstream response wrapped in a discovery envelope. The HTTP status mirrors the upstream status:

{
  "data": { "ok": true, "channel": "C123", "ts": "1715000000.000100" },
  "_meta": {
    "capability": "agent.action",
    "timestamp": "2026-05-18T10:40:55.123Z",
    "next_actions": [
      { "capability": "audit.query", "endpoint": "GET /v1/audit" },
      { "capability": "agent.permissions", "endpoint": "GET /v1/agent/permissions" }
    ],
    "docs": "https://api.agentvalet.ai/v1/openapi.json",
    "correlation_id": "0f4c9a61-2b7d-4e3a-9c85-6d1e0a2b3f47",
    "audit_id": "5d0e2f7a-3c1b-4a9e-8f6d-0b2c4e6a8d10"
  }
}

correlation_id is always present. audit_id is the audit row id (and the id of its signed receipt). connection appears when the proxy can say which connection served the call. If the audit write failed, _meta.audit_write_failed is true — the call still happened, so do not retry it.

A non-2xx upstream response is returned with the upstream status and body as-is, not wrapped.

If the org has PII redaction beta enabled and the agent has a per-platform visibility map, the data body is rewritten before the response is returned. The audit row records pii_detected, pii_categories, pii_redacted, and pii_record_count. See PII redaction.

Pending approval — 202 Accepted

When the agent’s grant for the platform has require_approval set (it applies to every call on that grant, reads included), or a policy or guardrail asks for approval:

{
  "status": "pending_approval",
  "approval_id": "7c1e4b2a-9d3f-4e8a-b6c5-2f0a1d9e8b34",
  "audit_id": "5d0e2f7a-3c1b-4a9e-8f6d-0b2c4e6a8d10",
  "message": "Owner approval required"
}

Your agent should poll GET /v1/approvals/:id until status is approved (with result populated) or denied / expired. The MCP platform tools do this long-poll for you for up to 50 seconds; after that it returns the 202 envelope and your agent should explain the wait to the user.

Approvals expire 10 minutes from creation. The owner is notified in the dashboard inbox, plus push (mobile) and delegate email on Team and above.

Error codes

All errors follow the common envelope. The error identifier is stable; where it is a sentence, the machine code is in reason or code (and in report_hint.suggested_payload.code).

Audit

Every governed call writes one row to audit_log with:

• action = the requested scope
• result = allowed / denied / pending_approval / error
• request_id = the response’s correlation_id
• metadata.response_status from the upstream
• pii_* columns if PII redaction ran
• Forensic columns (ip_address, user_agent, geo_country, etc.) if your org has forensic capture enabled