Docs · Arlo

Get started

Overview

The Arlo API is a workspace-scoped REST API at https://api.arlo.sh. Authenticate with a bearer token, target a workspace with the X-Arlo-Workspace-Id header, and call governed agent runs, tasks, memory, skills, files, integrations, automations, and mini apps.

Authentication

Every request needs an Authorization: Bearer token and an X-Arlo-Workspace-Id header naming the workspace to act in.

Making requests

Base URL, required headers, the bare response shape, and pagination.

Errors

Errors return { ok: false, error, escalation } with a matching HTTP status.

Rate limits

Planned: per-workspace request and token limits surfaced via X-RateLimit headers.

API reference

GET/v1/me

Get the current user and workspace

GET/v1/workspaces

List the caller's workspaces

GET/v1/dashboard

Get the workspace dashboard summary

GET/v1/activity

List the workspace activity feed

POST/v1/runs

Run Arlo once and get the reply

POST/v1/chat/stream

Stream a chat conversation (SSE)

GET/v1/tasks

List background tasks

GET/v1/tasks/{task_id}/timeline

Get a task with its full execution trace

GET/v1/sessions

List live-chat sessions

GET/v1/sessions/{session_id}/timeline

Get a session with its full trace

GET/v1/traces/{trace_id}

Get a raw execution trace

GET/v1/memories

List memories the caller can see

POST/v1/memories

Create a memory

PATCH/v1/memories/{id}

Update or promote a memory

DELETE/v1/memories/{id}

Delete a memory

GET/v1/skills

List draft and active skills

PATCH/v1/skills/{id}

Update a skill

POST/v1/skills/{id}/approve

Approve a draft skill

POST/v1/skills/{id}/reject

Reject a draft skill

POST/v1/skills/{id}/promote

Promote a skill's scope

DELETE/v1/skills/{id}

Deprecate a skill

GET/v1/files

List workspace files

GET/v1/files/{id}/content

Get a file's content

POST/v1/files/{id}/share

Create a temporary share link

GET/v1/library

List the unified library

POST/v1/library/{id}/promote

Promote an item to the company library

DELETE/v1/library/{id}

Soft-delete a library item

POST/v1/library/{id}/restore

Restore a soft-deleted item

GET/v1/integrations

List connected integrations

GET/v1/integrations/composio/toolkits

Search the app toolkit catalog

POST/v1/integrations/connect

Connect an integration

DELETE/v1/integrations/connections/{connectionId}/accounts/{accountId}

Disconnect an integration

GET/v1/automations

List automations

POST/v1/automations

Create an automation

GET/v1/automations/{id}

Get an automation

POST/v1/automations/{id}/run-now

Enqueue an on-demand run

GET/v1/automations/{id}/runs

List an automation's runs

POST/v1/automations/{id}/dry-run

Plan a run without side effects

POST/v1/automations/{id}/schedule

Create a recurring schedule

POST/v1/automations/{id}/subscribe

Trigger an automation on an event

GET/v1/mini-apps

List mini apps

POST/v1/mini-apps

Propose a mini app

GET/v1/mini-apps/{id}

Get a mini app

GET/v1/mini-apps/{id}/records

List a mini app's records

POST/v1/mini-apps/{id}/records

Create a mini-app record

PUT/v1/mini-apps/{id}/records/{recordId}

Update a mini-app record

DELETE/v1/mini-apps/{id}/records/{recordId}

Delete a mini-app record

GET/v1/teams

List teams

POST/v1/teams

Create a team

GET/v1/team

List directory contacts

POST/v1/team/invites

Create an invite link

GET/v1/team/invites/{token}

Resolve an invite (no auth)

GET/v1/approvals

List pending approvals

POST/v1/approvals/{id}/decide

Approve or deny a governed action

GET/v1/escalations

List escalations

POST/v1/escalations/{id}/resolve

Resolve an escalation

GET/v1/billing

Get the billing overview

GET/v1/usage

Get usage metrics

POST/v1/billing/checkout

Create a Stripe checkout session

GET/v1/onboarding

Get onboarding status

POST/v1/onboarding/complete

Mark onboarding complete

Webhook events

session.completed

A session finished successfully.

session.failed

A session ended with a typed error.

skill.proposed

Arlo proposed a skill draft or revision.

skill.updated

A skill version became active.

approval.requested

A governed action is waiting for a decision.

approval.decided

An approval was allowed or denied.

audit.alert

Audit verification or policy monitoring raised an alert.

file.created

A workspace file or version was created.

memory.proposed

Arlo proposed a memory write.

dream.completed

Daily organization finished.

automation_suggestion.created

Arlo suggested a recurring automation.

mini_app.proposed

Arlo proposed a team mini app.

mini_app.published

A team mini app was published.

meeting.completed

Meeting notes and action items are ready.

call.completed

A phone check-in completed.

CLI

curl -fsSL https://arlo.sh/install | sh

arlo init

Scaffold an arlo.json in the current directory.

arlo init --workspace ws_acme

arlo login

Store a workspace bearer token for the active workspace.

arlo login --workspace ws_acme

arlo whoami

Print the active workspace and user.

arlo whoami

arlo run

Run Arlo once and print the reply.

arlo run "summarize the renewal thread"

arlo chat

Open a streaming REPL with Arlo.

arlo chat

arlo connect

Connect an app integration with an explicit scope.

arlo connect gmail --scope individual

Concepts and operations

Runs and sessions

A run is one governed execution; a session is the conversation it belongs to.

Memory

Memory is scoped to where it was learned: session, individual, team, or company.

Skills

Repeated workflows become reviewed, versioned skills.

Scopes and governance

Scopes decide visibility; governance gates risky tool calls behind approvals.

Operations guide

Runbooks cover traces, audit exports, policy decisions, rate limits, release evidence, and incident review.