Create & Configure

Define agents with instructions, model selection, and tool restrictions

An agent is a reusable definition — a name, instructions, and optional configuration. Create it once, then run it many times with different prompts.

Create an agent

Endpoint

POST /agent/v1/agents

cURL

curl -X POST https://api.case.dev/agent/v1/agents \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Discovery Analyst",
    "instructions": "You are a legal discovery analyst. When given a vault ID and topic:\n1. Search the vault for relevant documents\n2. Analyze key passages\n3. Compile a summary memo with citations\nUse the casedev CLI for all vault and search operations."
  }'

Response

{
  "id": "agent_abc123xyz",
  "name": "Discovery Analyst",
  "instructions": "You are a legal discovery analyst...",
  "model": "anthropic/claude-sonnet-4.6",
  "vaultIds": null,
  "enabledTools": null,
  "disabledTools": null,
  "sandbox": null,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Configuration options

Property	Type	Default	Description
name	string	required	Display name for the agent
instructions	string	required	System prompt that defines behavior
description	string	optional	Human-readable description
model	string	anthropic/claude-sonnet-4.6	LLM model identifier
vaultIds	string[]	all vaults	Restrict to specific vault IDs
enabledTools	string[]	all tools	Allowlist of tools
disabledTools	string[]	none	Denylist of tools
sandbox	object	default	Custom sandbox resources

Object-level scoping (objectIds) is set per-run, not per-agent. This allows the same agent to work with different document sets on each execution. See Execute Runs → Object ID scoping.

Model selection

Override the default model per agent. Any model available through the LLM Gateway works:

cURL

curl -X POST https://api.case.dev/agent/v1/agents \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fast Summarizer",
    "instructions": "Summarize documents concisely.",
    "model": "anthropic/claude-haiku-3.5"
  }'

Vault restrictions

Lock an agent to specific vaults so it can only access authorized data:

cURL

curl -X POST https://api.case.dev/agent/v1/agents \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Case 2024-1234 Analyst",
    "instructions": "Analyze documents in your assigned vault.",
    "vaultIds": ["vault_abc123", "vault_def456"]
  }'

Tool restrictions

Control which tools the agent can use. Either allowlist specific tools, or denylist ones you want to block:

cURL

curl -X POST https://api.case.dev/agent/v1/agents \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Only",
    "instructions": "Research legal questions. Do not modify any files.",
    "enabledTools": ["bash", "read", "grep", "glob"],
    "disabledTools": ["write", "edit"]
  }'

Sandbox resources

Customize CPU and memory for compute-intensive tasks:

cURL

curl -X POST https://api.case.dev/agent/v1/agents \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Heavy Processor",
    "instructions": "Process large document sets.",
    "sandbox": {"cpu": 4, "memoryMiB": 4096}
  }'

Default sandbox: 2 CPU, 2048 MiB memory. The sandbox has a 30-minute execution timeout.

Writing good instructions

The instructions field is the agent’s system prompt. It defines personality, capabilities, and constraints. Tips:

1. Be specific about tools. Tell the agent to use casedev CLI for vault operations, legal search, etc.
2. Define the output format. “Write a markdown report” or “Return a JSON summary.”
3. Set boundaries. “Only search the assigned vault” or “Do not modify existing documents.”
4. Include workflow steps. Numbered steps help the agent stay on track for complex tasks.

cURL

curl -X POST https://api.case.dev/agent/v1/agents \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deposition Summarizer",
    "instructions": "You summarize depositions. For each deposition:\n1. Use casedev vault search to find the document\n2. Read the full transcript\n3. Identify key admissions, contradictions, and timeline facts\n4. Write a 1-page summary in markdown\n5. Upload the summary to the same vault using casedev vault upload\n6. Return the vault object ID and a presigned download URL\n\nAlways cite page numbers. Use formal legal writing style."
  }'

Update an agent

Endpoint

PATCH /agent/v1/agents/:id

Partial updates — only provided fields change:

cURL

curl -X PATCH "https://api.case.dev/agent/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-sonnet-4.6"}'

List agents

Endpoint

GET /agent/v1/agents

Returns active agents in your organization with cursor-based pagination.

cURL

curl "https://api.case.dev/agent/v1/agents?limit=20" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Query parameters

Parameter	Type	Required	Description
limit	integer	no	Max results per page (1-250, default 50)
cursor	string	no	Agent ID from a previous page’s nextCursor

Response

{
  "agents": [
    {
      "id": "agent_abc123",
      "name": "Discovery Analyst",
      "description": null,
      "model": "anthropic/claude-sonnet-4.6",
      "isActive": true,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Delete an agent

Endpoint

DELETE /agent/v1/agents/:id

Soft-deletes the agent and revokes its scoped API key. Existing run data is preserved.

cURL

curl -X DELETE "https://api.case.dev/agent/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $CASEDEV_API_KEY"

Next: Execute runs

Now that you have an agent, learn how to create and execute runs →