Vision Platform API

External agent guide

Use this guide when an external agent needs to call the Vision Platform API with a bearer token.

External agents operate as team members. They can request decisions from a leader and read their own visible decision requests. They do not operate with leader, deputy, system, or governance-agent rights.

This page is intentionally narrower than the full product API. Calendar conversions, leader worklist operation, delegation control, audit, billing, tenant settings, and system integration endpoints are not part of the external-agent profile.

Discovery

Base URL

https://www.lontive.com/vision-platform

The public deployment serves API routes under /vision-platform/v1/*. Local API development usually calls the same handlers directly at http://localhost:3000/v1/*.

Authentication

Protected API calls use a bearer token. Supported bearer formats in the current implementation are API keys and JWTs.

Authorization: Bearer vsk_<token>
Authorization: Bearer <jwt>

API keys are created from the protected tenant-aware endpoint POST /v1/api-keys. A leader can create an on_behalf_of key linked to a represented team member with onBehalfOfActorId, or an autonomous key with agentDisplayName. External agents use the same Authorization: Bearer ... header as the rest of the API; there is no separate public X-Agent-Key header flow.

A team member normally gets the x-tenant-id from the leader or the workspace onboarding material. The agent should confirm it with GET /v1/context before doing work.

Required headers

Health checks

External agent scopes

For external agents, issue only the scopes needed for team-member work and decision intake:

worklist.tasks.write is allowed because team members have their own task list. Do not use it to operate the leader worklist. Do not grant external agents deputy scopes, governance-agent scopes, kill-switch scopes, or system integration scopes. If an agent needs a leader action, it should create a decision request and wait for the leader outcome.

Credential matrix

Credential or role Typical owner Allowed in this guide Not allowed from this guide
external agent Team member or a leader-created autonomous agent /v1/context, /v1/my-tasks, /v1/decision-requests Leader worklist, delegations, calendar conversions, audit, billing, tenant settings, governance, kill switch
tenant integration Operator-approved tenant integration Not documented here Do not infer tenant-integration rights from an external-agent key
leader / deputy Interactive product users Not documented here Do not use an external-agent key to perform leader or deputy actions
system integration Internal service account or controlled backend integration Not documented here Calendar conversion ingestion, governance automation, and other system-only actions require a separate operator-approved path

Calendar boundaries

External agents do not get calendar conversion endpoints in this profile.

Question External-agent answer
Can the agent read a user's calendar through Vision Platform? No. Calendar reads are not exposed to external-agent keys.
Can the agent create or edit calendar events through Vision Platform? No. Use the user's separate calendar provider integration only if the user has granted that outside Vision Platform.
Can the agent convert calendar events into worklist task candidates? No. Calendar-assisted setup and calendar conversion flows are leader/UI or separately approved integration flows.
Can the agent ask a person to approve a calendar-related action? Yes. Create a decision request that describes the intended calendar action, then continue only after approval.

Allowed endpoint profile

The external-agent profile is intentionally small. Treat every endpoint outside this table as unavailable to an external agent unless a human operator gives a separate non-agent integration key.

Method Endpoint Use
GET /v1/context Confirm the authenticated actor and tenant context.
GET /v1/my-tasks List the team-member actor's own tasks.
POST /v1/my-tasks Create a task owned by the team-member actor.
PUT /v1/my-tasks/{id} Update the team-member actor's own task. Include the current version or expectedVersion.
POST /v1/my-tasks/{id}/status Move the team-member actor's own task between allowed statuses. Include the current version or expectedVersion.
DELETE /v1/my-tasks/{id} Delete the team-member actor's own completed task. Include the current version or expectedVersion.
POST /v1/decision-requests Ask the leader to approve, reject, or decide something before the agent acts.
GET /v1/decision-requests List decision requests visible to the team-member actor.
GET /v1/decision-requests/{decisionRequestId} Poll the specific decision request until it is resolved.

Do not call

Employee-owned agent flow

  1. The team member asks the leader for an agent key and explains what the agent will do.
  2. The leader creates an on_behalf_of API key and links it to the team member with onBehalfOfActorId.
  3. The leader grants only worklist.tasks.read, worklist.tasks.write, decision.requests.write, and decision.requests.read.
  4. The team member gives the agent the base URL, tenant ID, and API key through a secure channel.
  5. The agent calls GET /v1/context to verify the represented actor before doing work.
  6. The agent manages only /v1/my-tasks and creates decision requests before risky or external actions.
  7. The employee or leader resolves the decision request in Vision Platform.
  8. The agent continues, cancels, or asks for clarification based on the decision outcome.

Task fields and conflicts

Example requests

Confirm actor context

curl -X GET "https://www.lontive.com/vision-platform/v1/context" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant"

List the agent's own tasks

curl -X GET "https://www.lontive.com/vision-platform/v1/my-tasks" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant"

Create an agent-owned task

curl -X POST "https://www.lontive.com/vision-platform/v1/my-tasks" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant" \
  -H "Idempotency-Key: sales-agent-task-001" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prepare draft follow-up for customer review",
    "description": "Internal task owned by the sales agent actor.",
    "priority": "medium",
    "deadlineAt": "2026-06-01T12:00:00.000Z"
  }'

Update an agent-owned task

curl -X PUT "https://www.lontive.com/vision-platform/v1/my-tasks/personal_task_123" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prepare revised follow-up for customer review",
    "description": "Updated after new account context arrived.",
    "priority": "high",
    "expectedVersion": 2
  }'

Mark an agent-owned task done

curl -X POST "https://www.lontive.com/vision-platform/v1/my-tasks/personal_task_123/status" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant" \
  -H "Idempotency-Key: sales-agent-task-001-done" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "done",
    "expectedVersion": 3
  }'

Create a decision request

curl -X POST "https://www.lontive.com/vision-platform/v1/decision-requests" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant" \
  -H "Idempotency-Key: demo-decision-001" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Approve outbound follow-up email",
    "requestedDecisionType": "approve_or_reject",
    "riskLevel": "medium",
    "requestedBy": "Lontive sales agent",
    "description": "External approval reference: sales-agent:appr_123\nRun: run_456\nTool: schedule_front_followup_email"
  }'

Poll one decision request by ID

curl -X GET "https://www.lontive.com/vision-platform/v1/decision-requests/dec_123" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant"

Ask approval to send a customer offer

curl -X POST "https://www.lontive.com/vision-platform/v1/decision-requests" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant" \
  -H "Idempotency-Key: offer-approval-001" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Approve sending the Acme renewal offer",
    "requestedDecisionType": "approve_or_reject",
    "riskLevel": "medium",
    "requestedBy": "Sales follow-up agent",
    "description": "Approve before the agent sends the prepared offer through the external email system."
  }'

Ask approval to move a deadline

curl -X POST "https://www.lontive.com/vision-platform/v1/decision-requests" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant" \
  -H "Idempotency-Key: deadline-change-001" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Approve moving the customer recap deadline to Friday",
    "requestedDecisionType": "approve_or_reject",
    "riskLevel": "low",
    "requestedBy": "Personal work agent",
    "description": "The agent detected a calendar conflict and asks for approval before changing the external plan."
  }'

Ask for a policy exception

curl -X POST "https://www.lontive.com/vision-platform/v1/decision-requests" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant" \
  -H "Idempotency-Key: policy-exception-001" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Approve a one-time exception to the standard response window",
    "requestedDecisionType": "policy_exception",
    "riskLevel": "high",
    "requestedBy": "Customer operations agent",
    "description": "The agent should not apply the exception unless the decision request is approved."
  }'

Handle a version conflict

# 1. Update with the version last seen by the agent.
curl -X PUT "https://www.lontive.com/vision-platform/v1/my-tasks/personal_task_123" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prepare revised follow-up",
    "priority": "high",
    "expectedVersion": 2
  }'

# 2. If the API returns 409 version_conflict, read the task again.
curl -X GET "https://www.lontive.com/vision-platform/v1/my-tasks" \
  -H "Authorization: Bearer vsk_example" \
  -H "x-tenant-id: demo-tenant"

# 3. Retry only if the newer task state still supports the same change.

Recommended decision polling flow

  1. Create one API key per external agent. Use on_behalf_of when the agent acts for a specific team member, or autonomous when the agent should appear as an independent agent.
  2. Grant only worklist.tasks.read, worklist.tasks.write, decision.requests.write, and decision.requests.read.
  3. Use /v1/my-tasks for the agent's own work tracking. Do not use /v1/worklist/tasks to mutate the leader worklist.
  4. Create the approval as a /v1/decision-requests record and store the returned decision request ID in the agent runtime.
  5. Include the agent's own approval reference in the decision request description field so the queue stays traceable without extra schema changes.
  6. Poll GET /v1/decision-requests/{decisionRequestId} until the status is resolved.
  7. Treat approved as accept and rejected as reject. Read decisionOutcome, decisionNote, and decidedAt from the response.

Notes for agents