Agent Seats: quick start

Early access — contact us to enable Agent Seats on your workspace. Self-serve purchase isn't live yet.

What's an agent seat?

An agent seat is a technician identity for an AI agent, not a customer or a login. It can be assigned tickets, post comments, log billable hours, and change ticket status — all over a token API instead of a password. Everything it does shows up exactly like a human tech's work (including in hours reports), scoped to a quiet visibility level by default so it doesn't clutter anyone's queue.

Setup

1. In your workspace, go to Admin → Agent Seats.
2. Name the seat (e.g. "Claude") and click Create agent seat.
3. Copy the bearer token — it looks like agt_<hex>.
4. Send it as Authorization: Bearer agt_<hex> on every API call below.

Lost the token? Rotate or revoke it from the same page — rotating invalidates the old one immediately.

The API

Requests go to your apex host (no subdomain), e.g. https://ravinedesk.com/api/agent/... — the token identifies which workspace and technician you're acting as. Every route is per-token rate-limited, so one agent can't starve another tenant's.

List tickets

curl "https://ravinedesk.com/api/agent/tickets?filter=open" \
  -H "Authorization: Bearer agt_xxxxxxxxxxxxxxxx"

filter is optional — omit it for everything assignable to this seat.

List clients

curl https://ravinedesk.com/api/agent/clients \
  -H "Authorization: Bearer agt_xxxxxxxxxxxxxxxx"

Create a ticket

curl -X POST https://ravinedesk.com/api/agent/tickets \
  -H "Authorization: Bearer agt_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": 12,
    "title": "Renew SSL cert on staging",
    "description": "Cert expires in 3 days.",
    "type": "request",
    "priority": "high",
    "visibility": "agent"
  }'

Leave out visibility and it defaults to agent — the silent ledger — so a ticket the agent opens for itself never surfaces to the client or the default tech list.

Add a comment (and log hours)

curl -X POST https://ravinedesk.com/api/agent/ticket/482/comments \
  -H "Authorization: Bearer agt_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Renewed the cert and restarted nginx.",
    "hours": 0.5,
    "isInternal": false
  }'

hours rolls straight into the client's hours report, same as a human tech's logged time.

Update status, priority, or visibility

curl -X POST https://ravinedesk.com/api/agent/ticket/482 \
  -H "Authorization: Bearer agt_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "visibility": "internal"
  }'

All three fields are optional and independent — send only what changed.

Visibility levels

Promote a ticket from agent to internal when it actually needs a person's attention. Nothing an agent does changes the numbering on client-facing ticket lists.

For Claude Code users

Since the API is just bearer-token REST, a Claude Code session can work as an agent seat directly — no plugin needed, just curl or an HTTP tool. A short protocol block in the workspace's CLAUDE.md keeps it well-behaved:

# Ravine Desk agent seat protocol
- Session start: GET /api/agent/tickets?filter=open — pick up anything assigned to this seat.
- File all new work through the API with visibility "agent" (the default). That's a silent
  ledger, not a customer-facing status — don't set "client" yourself.
- When something needs a human, POST /api/agent/ticket/{id} with visibility "internal" so it
  lands in the real queue.
- Log real hours on every comment (POST .../comments with "hours") — they roll into the
  client's hours report same as anyone else's time.

Early access

Self-serve purchase isn't live yet. Agent Seats are a paid add-on available on any plan; contact us and we'll enable one on your workspace.