Agent/API quickstart

The Agent/API lets an external client read bounded data from one workspace and prepare governed create/update proposals. It does not provide an embedded chat assistant, and an agent token can never approve its own proposal.

Before you begin

You need:

• a verified RecurLens account;
• access to the target workspace;
• its workspace ID; and
• an Agent/API token with the required scope.

The active workspace ID is present in authenticated workspace API requests. In your browser's developer tools, open Network, reload RecurLens, and copy the UUID after /api/v1/workspaces/ from a workspace request.

1. Create a read-only token

1. In RecurLens, switch to the workspace the client should access.
2. Open Settings → Agent tokens (beta).
3. Enter a descriptive token name.
4. Keep only Read subscriptions selected for this quickstart.
5. Choose an expiry (maximum 90 days), then create the token.
6. Copy the rlat_v1.<lookup>.<secret> token immediately. RecurLens shows it only once.

Treat the token like a password: do not commit it, log it, place it in a URL, or paste it into a shared conversation. Revoke it from Settings when no longer needed.

2. Configure your shell

export RECURLENS_API_URL="https://api.recurlens.com/api/v1"
export WORKSPACE_ID="00000000-0000-0000-0000-000000000001"
export AGENT_TOKEN="rlat_v1.REPLACE_LOOKUP.REPLACE_SECRET"

These values are placeholders. Keep real credentials in your local secret store.

3. Make the first read call

Every read tool is a POST with a JSON body:

curl --fail-with-body --silent --show-error \
  --request POST \
  "$RECURLENS_API_URL/workspaces/$WORKSPACE_ID/agent-tools/list_subscriptions" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"limit": 20, "sortBy": "renewalDate", "sortDirection": "asc"}'

A successful response uses the stable envelope:

{
  "success": true,
  "requestId": "...",
  "data": [],
  "meta": {
    "apiVersion": "v1",
    "timezone": "UTC",
    "hasMore": false,
    "nextCursor": null
  },
  "error": null
}

Use meta.nextCursor verbatim when meta.hasMore is true. Cursors are opaque; do not decode, construct, or reuse them across endpoints.

Save the requestId when reporting a failure. It correlates the response with server-side diagnostics without exposing your token.

Available read tools

Governed writes

Tokens may separately receive subscriptions:create and subscriptions:update. Those tools require a 16–128 character Idempotency-Key and return a pending proposal with an approval URL. They do not write immediately.

The same signed-in user to whom the originating token is bound reviews the proposal in RecurLens and must still have workspace write access. On confirmation, the server rechecks user access, token quota, validation, and (for updates) the expected record version, then executes at most once. Delete, archive, status change, cancellation, and purchasing are not Agent/API tools.

Errors and safe retries

Only retry when error.retryable is true, honoring retryAfterSeconds. Validation, access, proposal, idempotency, and version errors require a changed request. GLOBAL_CAP_REACHED is a structural halt even though it uses HTTP 503; stop and investigate rather than retrying.

For more diagnosis steps, see Troubleshooting.

See the complete API reference for request and response schemas.