Getting Started with Alloy

Go from zero to managing tickets in 5 minutes — using nothing but curl.

Prerequisites

• Rust toolchain (1.75+): Install via rustup if you don’t have it
• Git: To clone the repository
• curl and jq: For interacting with the API

Or use a prebuilt binary from the Releases page — no Rust toolchain needed.

Step 1: Start the Server

Alloy runs in SQLite mode by default — no database setup, no Docker, no config files. JWT signing keys are auto-generated if not configured.

# Clone and enter the repo
git clone https://github.com/your-org/alloy.git
cd alloy

# Build the release binary
cargo build --release

# Start the server with open registration enabled
ALLOY_REGISTRATION=open ./target/release/alloy serve

Expected output:

WARN: No JWT keys configured — auto-generating Ed25519 key pair for development.
       Set ALLOY_JWT_PRIVATE_KEY / ALLOY_JWT_PUBLIC_KEY for production.
Running migrations...
Migrations complete.
Listening on 0.0.0.0:3000

Note: The auto-generated keys are ephemeral — they change on every restart, which invalidates existing tokens. For production, set ALLOY_JWT_PRIVATE_KEY_FILE and ALLOY_JWT_PUBLIC_KEY_FILE pointing to Ed25519 PEM files. See the Deployment Guide for details.

Leave this terminal running and open a new one for the remaining steps. Set the base URL variable:

BASE_URL="http://localhost:3000"

Step 2: Register a User

Create your first user account via the registration endpoint:

curl -s -X POST "$BASE_URL/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "tutorial@alloy.dev",
    "password": "tutorial1",
    "display_name": "Tutorial User"
  }' | jq .

{
  "user_id": "a1b2c3d4-...",
  "email": "tutorial@alloy.dev",
  "display_name": "Tutorial User",
  "access_token": "eyJ..."
}

Save the token and user ID for subsequent requests:

TOKEN="<access_token from above>"
USER_ID="<user_id from above>"

CLI equivalent:

cargo run -p alloy-cli -- auth login --email tutorial@alloy.dev --password tutorial1

Step 3: Create an Organization

curl -s -X POST "$BASE_URL/api/v1/orgs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Tutorial Corp",
    "slug": "tutorial-corp"
  }' | jq .

{
  "id": "b2c3d4e5-...",
  "name": "Tutorial Corp",
  "slug": "tutorial-corp"
}

Save the org ID:

ORG_ID="<id from above>"

Verify it was created:

curl -s "$BASE_URL/api/v1/orgs" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "b2c3d4e5-...",
      "name": "...",
      "slug": "..."
    }
  ]
}

CLI equivalent:

cargo run -p alloy-cli -- onboard --email tutorial@alloy.dev --password tutorial1 --org-name "Tutorial Corp" --org-slug tutorial-corp

Roles and Permissions

When you created the organization above, Alloy automatically assigned you the Owner role — the most privileged role available. Every organization member has exactly one of five roles:

Inviting a Team Member

As an Owner, you can invite others to join your organization. Each invite specifies the role the new member will receive:

curl -s -X POST "$BASE_URL/api/v1/orgs/$ORG_ID/invites" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"email\": \"teammate@example.com\",
    \"role\": \"member\",
    \"created_by\": \"$USER_ID\"
  }" | jq .

{
  "id": "...",
  "invite_code": "...",
  "invite_link": "...",
  "email": "teammate@example.com",
  "role": "Member",
  "expires_at": "..."
}

Share the invite_link with your teammate. They can register using the invite code to join with the specified role.

For the full permission matrix showing which role is required for each operation, see the Roles and Permissions section of the API Reference.

Step 4: Create a Project

curl -s -X POST "$BASE_URL/api/v1/projects" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"org_id\": \"$ORG_ID\",
    \"key\": \"DEMO\",
    \"name\": \"Demo Project\",
    \"description\": \"A demo project for Alloy\"
  }" | jq .

{
  "id": "c3d4e5f6-...",
  "org_id": "b2c3d4e5-...",
  "key": "DEMO",
  "name": "Demo Project",
  "description": "A demo project for Alloy"
}

Save the project ID:

PROJECT_ID="<id from above>"

Read it back to confirm:

curl -s "$BASE_URL/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "id": "c3d4e5f6-...",
  "key": "DEMO",
  "name": "Demo Project",
  "description": "A demo project for Alloy"
}

CLI equivalent:

cargo run -p alloy-cli -- project create --org-id "$ORG_ID" --key DEMO --name "Demo Project"

Step 5: Create Your First Ticket

curl -s -X POST "$BASE_URL/api/v1/projects/$PROJECT_ID/tickets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"title\": \"Set up CI pipeline\",
    \"description\": \"Configure GitHub Actions for build and test\",
    \"status\": \"Backlog\",
    \"priority\": \"High\",
    \"reporter_id\": \"$USER_ID\"
  }" | jq .

{
  "id": "d4e5f6g7-...",
  "title": "Set up CI pipeline",
  "description": "Configure GitHub Actions for build and test",
  "status": "Backlog",
  "priority": "High",
  "reporter_id": "a1b2c3d4-..."
}

Save the ticket ID:

TICKET_ID="<id from above>"

CLI equivalent:

cargo run -p alloy-cli -- ticket create --title "Set up CI pipeline" --priority high

Step 6: Add a Comment

curl -s -X POST "$BASE_URL/api/v1/tickets/$TICKET_ID/comments" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "{
    \"body\": \"Looks good, let's ship it\",
    \"author_id\": \"$USER_ID\"
  }" | jq .

{
  "id": "e5f6g7h8-...",
  "body": "Looks good, let's ship it",
  "author_id": "a1b2c3d4-...",
  "ticket_id": "d4e5f6g7-..."
}

CLI equivalent:

cargo run -p alloy-cli -- comment create --ticket-id "$TICKET_ID" --body "Looks good, let's ship it"

Step 7: List Tickets

Verify everything by listing tickets in the project:

curl -s "$BASE_URL/api/v1/projects/$PROJECT_ID/tickets" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "d4e5f6g7-...",
      "title": "Set up CI pipeline",
      "status": "Backlog",
      "priority": "High"
    }
  ]
}

CLI equivalent:

cargo run -p alloy-cli -- ticket list

You’re up and running!

Seed a Full Demo

Want a richer dataset to explore? The included seed script creates an org, user, project, labels, a sprint, six tickets, comments, and time entries — all with read-back validation:

BASE_URL=http://localhost:3000 bash scripts/seed-demo.sh

Learn More

References

• API Reference — Full endpoint documentation, field tables, and permission matrix
• CLI Reference — Complete list of commands and options for the Alloy CLI
• TUI Guide — Interactive terminal UI for browsing and managing work
• MCP Guide — Use Alloy through the Model Context Protocol with AI assistants
• MCP Tools Reference — Detailed reference for all MCP tool parameters and behavior
• Deployment — Production deployment with PostgreSQL, Docker, TLS, and multi-tenancy

Guides

• Projects & Tickets — Create and manage projects, tickets, and assignments
• Sprints & Boards — Plan sprints, track velocity, and visualize progress
• Workflows & Statuses — Define custom workflows and ticket lifecycle rules
• Time Tracking & Finance — Log time, approve entries, and generate financial reports
• Teams, Roles & Permissions — Manage org members, roles, and access control
• Labels, Tags & Organization — Categorize and filter work with labels and tags

Use Cases

• For Engineering Managers — Sprint planning, team velocity, and status reporting
• For Finance Teams — Time reports, capitalization, and budget tracking
• For DevOps & Platform Teams — Automation, API integration, and infrastructure workflows
• For Individual Developers — Daily workflow, ticket management, and time logging
• For Project Owners & Managers — Roadmap planning, cross-team coordination, and delivery tracking

Playbooks

• Running a Sprint — Step-by-step guide for PMs to plan and execute sprints
• Quarterly Finance Reporting — End-to-end reporting workflow for CFOs
• Setting Up a New Team — Onboarding checklist for engineering managers
• Automating Your Workflow — Recipes for DevOps teams to automate with the API

Tutorials

• End-to-End Walkthrough — Complete tutorial covering all major features
• API Automation with curl and jq — Script common workflows with shell commands
• Authentication Deep Dive — SSO, API keys, and token management explained
• MCP Workflow — Build AI-powered project management workflows

Alloy CLI Reference

Alloy is a headless, API-first project management tool. The CLI (alloy) lets you manage organizations, projects, tickets, sprints, time entries, and more from your terminal. For the HTTP API, see the API Reference. New to Alloy? Start with the Getting Started guide.

Global Flags

Every command accepts:

Output Formats

The --format flag controls how results are displayed:

TTY auto-detection: When output goes to an interactive terminal, format defaults to table. When piped or redirected, it defaults to json. Override with --format or the ALLOY_FORMAT environment variable.

The NO_COLOR environment variable suppresses ANSI color codes when set to any non-empty value.

Commands

health

Check API server connectivity and status.

alloy health [--format <FORMAT>]

Examples:

# Quick status check
alloy health

# Machine-readable health check for monitoring
alloy health --format json

migrate

Run database migrations against the configured database.

alloy migrate

Uses ALLOY_DATABASE_URL (default: sqlite://alloy.db). Migrations are embedded in the binary — no external migration files needed at runtime.

Examples:

# Run migrations against default SQLite database
alloy migrate

# Run migrations against PostgreSQL
ALLOY_DATABASE_URL=postgres://localhost/alloy alloy migrate

serve

Start the Alloy API server.

alloy serve [--db <URL>] [--port <PORT>]

Examples:

# Start with defaults (SQLite on port 3000)
alloy serve

# Start with PostgreSQL on a custom port
alloy serve --db postgres://localhost/alloy --port 8080

auth

Authenticate with the Alloy API and manage API keys.

auth login

Log in with email and password. Stores credentials locally.

alloy auth login --email <EMAIL> --password <PASSWORD>

Credentials are saved to ~/.config/alloy/credentials.toml and include the access token, refresh token, user ID, and email. The CLI automatically refreshes expired tokens on 401 responses.

Examples:

# Log in and save credentials
alloy auth login --email admin@example.com --password s3cret

# Log in and capture just the user ID
alloy auth login --email admin@example.com --password s3cret --format plain

auth token

Display the currently stored authentication token (masked for security).

alloy auth token

Shows the first 12 and last 4 characters of the token with the middle masked.

Examples:

# Check which account is logged in
alloy auth token

# Get token info as JSON
alloy auth token --format json

auth api-key create

Create a new API key with optional scope and project restrictions.

alloy auth api-key create --name <NAME> [--scopes <SCOPES>] [--projects <PROJECT_IDS>]

API keys are prefixed alloy_live_ (production) or alloy_test_ (testing). The full key is shown only once at creation time.

Scopes:

• read — Read-only access to resources
• write — Create, update, and delete resources
• admin — Full access including user and org management

Examples:

# Create a read-write key for CI
alloy auth api-key create --name "CI Pipeline"

# Create a read-only key restricted to one project
alloy auth api-key create --name "Dashboard" --scopes read --projects 550e8400-e29b-41d4-a716-446655440000

# Create an admin key and capture it for scripting
alloy auth api-key create --name "Admin Script" --scopes read,write,admin --format plain

auth api-key list

List all API keys for the current user.

alloy auth api-key list

Examples:

# View all API keys
alloy auth api-key list

# List keys as JSON for automation
alloy auth api-key list --format json

auth api-key revoke

Revoke an API key by its ID.

alloy auth api-key revoke <ID>

Examples:

# Revoke a specific key
alloy auth api-key revoke 550e8400-e29b-41d4-a716-446655440000

# List keys then revoke one
alloy auth api-key list --format json | jq '.[0].id' -r | xargs alloy auth api-key revoke

org

Manage organizations (tenants).

org create

alloy org create --name <NAME> --slug <SLUG>

Examples:

# Create a new organization
alloy org create --name "Acme Corp" --slug acme-corp

# Create and capture org ID
ORG_ID=$(alloy org create --name "Acme Corp" --slug acme-corp --format json | jq -r '.id')

org list

alloy org list

Examples:

# List all organizations
alloy org list

# Get org IDs for scripting
alloy org list --format json | jq '.[].id'

org switch

Set the active organization for subsequent commands.

alloy org switch <ID>

Examples:

# Switch active organization
alloy org switch 550e8400-e29b-41d4-a716-446655440000

# Switch to the first org
alloy org switch $(alloy org list --format json | jq -r '.data[0].id')

project

Manage projects within an organization.

project create

alloy project create --org-id <ORG_ID> --key <KEY> --name <NAME> [--description <DESC>] [--team-id <TEAM_ID>]

Examples:

# Create a backend project
alloy project create --org-id $ORG_ID --key BACK --name "Backend Services"

# Create with description
alloy project create --org-id $ORG_ID --key WEB --name "Web Frontend" --description "React SPA and design system"

project list

alloy project list --org-id <ORG_ID> [--cursor <CURSOR>] [--limit <LIMIT>]

Examples:

# List all projects in an org
alloy project list --org-id $ORG_ID

# Page through results
alloy project list --org-id $ORG_ID --limit 5 --cursor "next_cursor_value"

project get

alloy project get <ID>

Examples:

# Get project details
alloy project get 550e8400-e29b-41d4-a716-446655440000

# Get project as JSON
alloy project get $PROJECT_ID --format json

project update

alloy project update <ID> [--name <NAME>] [--description <DESC>] [--team-id <ID|none>] [--cap-type <capex|opex|none>] [--phase <preliminary|app-development|post-implementation|none>] [--cost-center-id <ID|none>] [--amortization-months <INT|none>]

Pass none to any optional field to unset it.

Examples:

# Rename a project
alloy project update $PROJECT_ID --name "Backend API v2"

# Set capitalization type for time tracking
alloy project update $PROJECT_ID --cap-type capex --phase app-development --amortization-months 36

project delete

alloy project delete <ID>

Examples:

# Delete a project
alloy project delete $PROJECT_ID

# Delete by key lookup
alloy project delete $(alloy project get $PROJECT_ID --format json | jq -r '.id')

project use

Set a default project context. This enables bare ticket number resolution (e.g., alloy ticket get 42 resolves to PROJ-42).

alloy project use <KEY_OR_ID>

Accepts either a project key (like BACK) or a UUID. The project ID and key are saved to ~/.config/alloy/credentials.toml.

Examples:

# Set default project by key
alloy project use BACK

# Set default project by UUID
alloy project use 550e8400-e29b-41d4-a716-446655440000

# Now bare numbers work everywhere
alloy ticket get 42     # resolves to BACK-42
alloy ticket list       # lists tickets in BACK

ticket

Create, list, update, and manage tickets. Supports smart ID resolution.

Smart ID Resolution: Ticket commands accept three reference formats:

Set project context with alloy project use <KEY> to enable bare number references.

ticket create

alloy ticket create [--project <PROJECT_ID>] [--title <TITLE>] [--description <DESC>] [--priority <PRIORITY>] [--status <STATUS>] [--assignee-id <UUID>] [--reporter-id <UUID>]

In interactive mode (TTY), missing fields are prompted with fuzzy selectors for projects, users, and priorities.

Examples:

# Create a ticket interactively (prompts for missing fields)
alloy ticket create

# Create a ticket non-interactively
alloy ticket create --project $PROJECT_ID --title "Fix login timeout" --priority high --status todo

# Create and capture the ticket ID
TICKET_ID=$(alloy ticket create --project $PROJECT_ID --title "Add caching" --format json | jq -r '.id')

ticket list

alloy ticket list [--project <PROJECT_ID>] [--status <STATUS>] [--priority <PRIORITY>] [--assignee-id <UUID>] [--cursor <CURSOR>] [--limit <LIMIT>]

Examples:

# List tickets in the default project
alloy ticket list

# Filter by status
alloy ticket list --status todo,in_progress

# List high-priority tickets as JSON
alloy ticket list --priority high --format json

# Page through results
alloy ticket list --limit 10 --cursor "next_cursor_value"

ticket get

alloy ticket get <ID>

Accepts UUID, KEY-NUMBER, or bare number.

Examples:

# Get by project-qualified reference
alloy ticket get BACK-42

# Get by bare number (uses default project)
alloy ticket get 42

# Get by UUID
alloy ticket get 550e8400-e29b-41d4-a716-446655440000

ticket update

alloy ticket update <ID> [--title <TITLE>] [--description <DESC>] [--status <STATUS>] [--priority <PRIORITY>] [--assignee-id <UUID|none>] [--add-label <LABEL_ID>] [--remove-label <LABEL_ID>]

In interactive mode with no flags, a multi-select dialog prompts for which fields to update with fuzzy selectors for users and labels.

Examples:

# Move a ticket to in-progress
alloy ticket update BACK-42 --status in_progress

# Assign and add a label
alloy ticket update 42 --assignee-id $USER_ID --add-label $LABEL_ID

# Interactive update (prompts for fields to change)
alloy ticket update BACK-42

ticket batch-update

alloy ticket batch-update --ticket-ids <UUID,UUID,...> [--title <TITLE>] [--description <DESC>] [--status <STATUS>] [--priority <PRIORITY>] [--assignee-id <UUID>] [--sprint-id <UUID>]

Apply the same field updates to multiple tickets at once. At least one field flag must be provided.

Examples:

# Set all tickets to high priority
alloy ticket batch-update --ticket-ids "$ID1,$ID2" --priority high

# Move multiple tickets to Done
alloy ticket batch-update --ticket-ids "$ID1,$ID2" --status Done

ticket batch-transition

alloy ticket batch-transition --ticket-ids <UUID,UUID,...> --to-status <STATUS>

Transition multiple tickets to the same target status. Each ticket is validated against its project’s workflow. Reports successes and failures individually.

Examples:

# Transition all sprint tickets to Done
alloy ticket batch-transition --ticket-ids "$ID1,$ID2" --to-status Done

comment

Add and manage comments on tickets.

comment add

alloy comment add --ticket <TICKET_REF> --body <BODY> --author-id <UUID> [--parent-id <COMMENT_ID>]

Examples:

# Add a comment to a ticket
alloy comment add --ticket BACK-42 --body "Deployed to staging" --author-id $USER_ID

# Reply to an existing comment (threaded)
alloy comment add --ticket 42 --body "Confirmed fixed" --author-id $USER_ID --parent-id $PARENT_COMMENT_ID

comment list

alloy comment list --ticket <TICKET_REF> [--cursor <CURSOR>] [--limit <LIMIT>]

Examples:

# List comments on a ticket
alloy comment list --ticket BACK-42

# Get comments as JSON
alloy comment list --ticket 42 --format json

comment get

alloy comment get <ID>

Examples:

# Get a specific comment
alloy comment get $COMMENT_ID

# Get comment as JSON
alloy comment get $COMMENT_ID --format json

comment update

alloy comment update <ID> --body <BODY>

Examples:

# Edit a comment
alloy comment update $COMMENT_ID --body "Updated: deployed to production"

# Update and verify
alloy comment update $COMMENT_ID --body "Fixed in v2.1" && alloy comment get $COMMENT_ID

comment delete

alloy comment delete <ID>

Examples:

# Delete a comment
alloy comment delete $COMMENT_ID

label

Manage labels for organizing tickets.

label create

alloy label create --org <ORG_ID> --name <NAME> --color <COLOR>

Examples:

# Create a bug label
alloy label create --org $ORG_ID --name bug --color "#FF0000"

# Create a feature label
alloy label create --org $ORG_ID --name feature --color "#00FF00"

label list

alloy label list --org <ORG_ID> [--cursor <CURSOR>] [--limit <LIMIT>]

Examples:

# List all labels
alloy label list --org $ORG_ID

# Get labels as JSON
alloy label list --org $ORG_ID --format json

label get

alloy label get <ID>

Examples:

# Get label details
alloy label get $LABEL_ID

label update

alloy label update <ID> [--name <NAME>] [--color <COLOR>]

Examples:

# Change label color
alloy label update $LABEL_ID --color "#0000FF"

# Rename a label
alloy label update $LABEL_ID --name "critical-bug"

label delete

alloy label delete <ID>

Examples:

# Delete a label
alloy label delete $LABEL_ID

workflow

Define custom workflows with statuses and allowed transitions.

workflow create

alloy workflow create --org-id <ORG_ID> --name <NAME> --statuses <JSON> --transitions <JSON>

Examples:

# Create a simple workflow
alloy workflow create --org-id $ORG_ID --name "Standard" \
  --statuses '[{"name":"Backlog","category":"todo"},{"name":"In Progress","category":"in_progress"},{"name":"Done","category":"done"}]' \
  --transitions '[{"from":"Backlog","to":"In Progress"},{"from":"In Progress","to":"Done"}]'

# Create a workflow with review step
alloy workflow create --org-id $ORG_ID --name "With Review" \
  --statuses '[{"name":"Todo","category":"todo"},{"name":"Working","category":"in_progress"},{"name":"Review","category":"in_progress"},{"name":"Done","category":"done"}]' \
  --transitions '[{"from":"Todo","to":"Working"},{"from":"Working","to":"Review"},{"from":"Review","to":"Done"},{"from":"Review","to":"Working"}]'

workflow list

alloy workflow list --org-id <ORG_ID> [--cursor <CURSOR>] [--limit <LIMIT>]

Examples:

# List workflows
alloy workflow list --org-id $ORG_ID

# Get workflow details as JSON
alloy workflow list --org-id $ORG_ID --format json

workflow show

alloy workflow show <ID>

Examples:

# Show workflow with statuses and transitions
alloy workflow show $WORKFLOW_ID

# Get workflow as JSON for editing
alloy workflow show $WORKFLOW_ID --format json

workflow update

alloy workflow update <ID> [--name <NAME>] [--statuses <JSON>] [--transitions <JSON>]

Examples:

# Rename a workflow
alloy workflow update $WORKFLOW_ID --name "Engineering Flow"

# Add a new status and transition
alloy workflow update $WORKFLOW_ID \
  --statuses '[{"name":"Todo","category":"todo"},{"name":"In Progress","category":"in_progress"},{"name":"QA","category":"in_progress"},{"name":"Done","category":"done"}]' \
  --transitions '[{"from":"Todo","to":"In Progress"},{"from":"In Progress","to":"QA"},{"from":"QA","to":"Done"}]'

workflow delete

alloy workflow delete <ID>

Examples:

# Delete a workflow
alloy workflow delete $WORKFLOW_ID

tag

Manage key-value tags on entities (projects, tickets, users, teams, time entries).

tag set

Set one or more key-value tags on an entity (upsert — creates or updates).

alloy tag set --org <ORG_ID> --entity-type <TYPE> --entity-id <ID> --tag <KEY=VALUE>...

Examples:

# Tag a project with environment and team
alloy tag set --org $ORG_ID --entity-type project --entity-id $PROJECT_ID \
  --tag env=production --tag team=backend

# Tag a ticket with a priority label
alloy tag set --org $ORG_ID --entity-type ticket --entity-id $TICKET_ID --tag sprint=12

tag get

Get all tags for an entity.

alloy tag get --org <ORG_ID> --entity-type <TYPE> --entity-id <ID>

Examples:

# Get tags for a project
alloy tag get --org $ORG_ID --entity-type project --entity-id $PROJECT_ID

# Get tags as JSON
alloy tag get --org $ORG_ID --entity-type ticket --entity-id $TICKET_ID --format json

tag delete

Delete a tag by key from an entity.

alloy tag delete --org <ORG_ID> --entity-type <TYPE> --entity-id <ID> --key <KEY>

Examples:

# Remove the "env" tag from a project
alloy tag delete --org $ORG_ID --entity-type project --entity-id $PROJECT_ID --key env

tag search

Search for entities by tag key-value pair.

alloy tag search --org <ORG_ID> --key <KEY> --value <VALUE> [--cursor <CURSOR>] [--limit <LIMIT>]

Examples:

# Find all entities tagged env=production
alloy tag search --org $ORG_ID --key env --value production

# Search with pagination
alloy tag search --org $ORG_ID --key team --value backend --limit 10 --format json

team

Manage teams within an organization.

team create

alloy team create --name <NAME> [--description <DESC>]

Examples:

# Create a team
alloy team create --name "Backend"

# Create with description
alloy team create --name "Platform" --description "Infrastructure and DevOps"

team list

alloy team list

Examples:

# List all teams
alloy team list

# Get teams as JSON
alloy team list --format json

team delete

alloy team delete <ID> [--cascade] [--dry-run]

Examples:

# Delete a team
alloy team delete $TEAM_ID

# Preview cascade delete
alloy team delete $TEAM_ID --cascade --dry-run

# Cascade delete team and all dependents
alloy team delete $TEAM_ID --cascade

project member

Manage project membership. Nested under project.

project member add

alloy project member add --project-id <PROJECT_ID> --user-id <USER_ID>

Examples:

# Add a user to a project
alloy project member add --project-id $PROJECT_ID --user-id $USER_ID

project member remove

alloy project member remove --project-id <PROJECT_ID> --user-id <USER_ID>

Examples:

# Remove a user from a project
alloy project member remove --project-id $PROJECT_ID --user-id $USER_ID

project member list

alloy project member list --project-id <PROJECT_ID>

Examples:

# List project members
alloy project member list --project-id $PROJECT_ID

# Get members as JSON
alloy project member list --project-id $PROJECT_ID --format json

report

Generate capitalization and finance reports.

report capitalization

Generate a capitalization report as JSON with optional grouping and filters.

alloy report capitalization --period <YYYY-MM> [--group-by <GROUP>] [--include-users] [--include-budget] [--team-id <ID>] [--user-id <ID>] [--cost-center-id <ID>] [--activity-type <TYPE>] [--tag <KEY:VALUE>]

Examples:

# Basic capitalization report
alloy report capitalization --period 2026-03

# Report grouped by team with user breakdowns
alloy report capitalization --period 2026-03 --group-by team --include-users

# Filtered report
alloy report capitalization --period 2026-03 --team-id $TEAM_ID --activity-type development

report export

Export a capitalization report as CSV to stdout.

alloy report export --period <YYYY-MM> [--team-id <ID>] [--user-id <ID>] [--cost-center-id <ID>] [--activity-type <TYPE>] [--tag <KEY:VALUE>]

Examples:

# Export March report as CSV
alloy report export --period 2026-03

# Save CSV to file
alloy report export --period 2026-03 > march-2026.csv

# Export filtered by team
alloy report export --period 2026-03 --team-id $TEAM_ID

export

Export complete project data as portable JSON or SQLite. Uses human-readable keys (emails, project keys, label names) instead of UUIDs.

alloy export [--org <ORG_ID>] [--project <KEY>] [--export-format <FORMAT>] [--output <FILE>]

Examples:

# Export everything as JSON (uses stored org from login)
alloy export

# Export with explicit org ID
alloy export --org $ORG_ID

# Export a single project
alloy export --project PROJ

# Save to file
alloy export --project PROJ > proj-backup.json

# Export as SQLite database
alloy export --export-format sqlite --output alloy-export.db

import

Import data from an Alloy JSON export file, a Jira JSON export, or a Linear JSON export. Reads from a file path or stdin. Supports --dry-run to preview what would be imported without making changes. Use --from jira or --from linear to import from external tools.

alloy import [FILE] [--org <ORG_ID>] [--from <SOURCE>] [--dry-run]

Examples:

# Import from an Alloy export file
alloy import backup.json

# Preview what would be imported
alloy import backup.json --dry-run

# Import from stdin (e.g. pipe from export)
alloy export --project PROJ | alloy import

# Import with explicit org ID
alloy import backup.json --org $ORG_ID

# Import from a Jira JSON export
alloy import jira-export.json --from jira

# Preview a Jira import without making changes
alloy import jira-export.json --from jira --dry-run

# Import from a Linear JSON export
alloy import linear-export.json --from linear

# Preview a Linear import without making changes
alloy import linear-export.json --from linear --dry-run

Jira import mapping:

Linear import mapping:

board

Show the sprint board — tickets organized by workflow status columns.

alloy board <SPRINT_ID> [--format <FORMAT>]

Table output shows the sprint header, then each status column with its ticket count and the tickets listed with priority, title, and assignee.

Examples:

# View the sprint board
alloy board $SPRINT_ID

# Get board as JSON for scripting
alloy board $SPRINT_ID --format json

# Pipe plain output for processing
alloy board $SPRINT_ID --format plain

burndown

Show sprint burndown chart data — daily progress with total, completed, and remaining ticket counts.

alloy burndown <SPRINT_ID> [--format <FORMAT>]

Table output shows a dated table with total, completed, and remaining columns.

Examples:

# View burndown data
alloy burndown $SPRINT_ID

# Get burndown as JSON
alloy burndown $SPRINT_ID --format json

# Export for a spreadsheet
alloy burndown $SPRINT_ID --format plain > burndown.tsv

sprint

Manage sprints within projects. Sprints have a lifecycle: planning → active → completed.

Use alloy board <sprint-id> to view the sprint board and alloy burndown <sprint-id> to view the burndown chart.

sprint create

alloy sprint create --project <PROJECT_ID> --name <NAME> --start-date <DATE> --end-date <DATE> [--goal <GOAL>]

Examples:

# Create a two-week sprint
alloy sprint create --project $PROJECT_ID --name "Sprint 12" \
  --start-date 2026-03-25 --end-date 2026-04-08 \
  --goal "Ship authentication and onboarding"

# Create a sprint and capture its ID
SPRINT_ID=$(alloy sprint create --project $PROJECT_ID --name "Sprint 13" \
  --start-date 2026-04-08 --end-date 2026-04-22 --format json | jq -r '.id')

sprint list

alloy sprint list --project <PROJECT_ID> [--cursor <CURSOR>] [--limit <LIMIT>]

Examples:

# List sprints for a project
alloy sprint list --project $PROJECT_ID

# Get sprints as JSON
alloy sprint list --project $PROJECT_ID --format json

sprint start

Transition a sprint from planning to active.

alloy sprint start <ID>

Examples:

# Start a sprint
alloy sprint start $SPRINT_ID

# Start and verify status
alloy sprint start $SPRINT_ID && alloy sprint list --project $PROJECT_ID

sprint complete

Transition a sprint from active to completed.

alloy sprint complete <ID>

Examples:

# Complete a sprint
alloy sprint complete $SPRINT_ID

time

Log and manage time entries for capitalization tracking. Entries follow a lifecycle: draft → submitted → approved.

time log

alloy time log [--user-id <UUID>] [--ticket <TICKET_REF>] [--project <PROJECT_ID>] [--date <DATE>] [--duration <MINUTES>] [--description <DESC>] [--activity-type <TYPE>]

Activity types: Coding, Testing, CodeReview, Design, Documentation, Meeting, Planning, DevOps, BugFix, Refactoring, Research, Support, Other

Examples:

# Log time interactively (prompts for missing fields)
alloy time log

# Log 90 minutes of coding against a ticket
alloy time log --ticket BACK-42 --duration 90 --activity-type Coding --description "Implemented auth middleware"

# Log time for yesterday
alloy time log --ticket 42 --duration 60 --activity-type CodeReview --date 2026-03-24

time list

alloy time list --ticket <TICKET_REF> [--cursor <CURSOR>] [--limit <LIMIT>]

Examples:

# List time entries for a ticket
alloy time list --ticket BACK-42

# Get time entries as JSON
alloy time list --ticket 42 --format json

time get

alloy time get <ID>

Examples:

# Get time entry details
alloy time get $TIME_ENTRY_ID

time submit

Move a time entry from draft to submitted for approval.

alloy time submit <ID>

Examples:

# Submit a time entry for approval
alloy time submit $TIME_ENTRY_ID

# Log and submit in one flow
ENTRY=$(alloy time log --ticket 42 --duration 60 --activity-type Coding --format json | jq -r '.id')
alloy time submit $ENTRY

time approve

Approve a submitted time entry (manager action).

alloy time approve <ID>

Examples:

# Approve a time entry
alloy time approve $TIME_ENTRY_ID

time report

Generate capitalization reports for a given month.

alloy time report --period <YYYY-MM> [--output <csv|json>]

Examples:

# Export March 2026 as CSV
alloy time report --period 2026-03

# Get report as JSON
alloy time report --period 2026-03 --output json

# Save CSV report to file
alloy time report --period 2026-03 > march-2026.csv

invite

Create and manage organization invitations.

invite create

alloy invite create --org-id <ORG_ID> [--email <EMAIL>] [--role <ROLE>]

Examples:

# Invite a specific person
alloy invite create --org-id $ORG_ID --email dev@example.com --role Member

# Create an open invite link for the team
alloy invite create --org-id $ORG_ID --role Member

# Get just the invite code for scripting
alloy invite create --org-id $ORG_ID --email new@example.com --format plain

invite list

alloy invite list --org-id <ORG_ID>

Examples:

# List pending invitations
alloy invite list --org-id $ORG_ID

# List invites as JSON
alloy invite list --org-id $ORG_ID --format json

onboard

First-run setup wizard. Creates the initial admin user, organization, and API key. Only works when no organizations exist in the system.

alloy onboard --email <EMAIL> --password <PASSWORD> --org-name <NAME> --org-slug <SLUG>

Returns an API key that is shown only once — save it immediately.

Examples:

# Set up a fresh Alloy instance
alloy onboard --email admin@example.com --password mysecretpw --org-name "Acme Corp" --org-slug acme

# Capture the API key for automation
API_KEY=$(alloy onboard --email admin@example.com --password mysecretpw \
  --org-name "Acme" --org-slug acme --format plain)

completions

Generate shell completion scripts.

alloy completions <SHELL>

Supported shells: bash, zsh, fish, powershell, elvish.

Examples:

# Generate Zsh completions
alloy completions zsh > ~/.zfunc/_alloy

# Generate Bash completions
alloy completions bash > /etc/bash_completion.d/alloy

usage

Print agent-optimized self-documentation (<1500 tokens). Useful for LLM agents that need to discover available commands.

alloy usage [SUBCOMMAND]

Examples:

# Get concise overview of all commands
alloy usage

# Get detailed help for a specific command
alloy usage ticket

Credential Storage

Credentials are stored at ~/.config/alloy/credentials.toml (platform-specific via the directories crate). The file contains:

access_token = "eyJ..."
refresh_token = "abc123..."
user_id = "550e8400-..."
email = "admin@example.com"
org_id = "660e8400-..."          # set by `alloy org switch`
project_id = "770e8400-..."      # set by `alloy project use`
project_key = "BACK"             # set by `alloy project use`

The CLI auto-refreshes expired tokens: on a 401 response, it calls /api/v1/auth/refresh with the stored refresh token, updates credentials on disk, and retries the original request.

Common Workflows

Create an organization and invite your team

# First-time setup
alloy onboard --email admin@acme.com --password s3cretpw \
  --org-name "Acme Corp" --org-slug acme

# Log in
alloy auth login --email admin@acme.com --password s3cretpw

# Create a project
alloy project create --org-id $ORG_ID --key BACK --name "Backend"
alloy project use BACK

# Invite team members
alloy invite create --org-id $ORG_ID --email dev1@acme.com --role Member
alloy invite create --org-id $ORG_ID --email dev2@acme.com --role Member
alloy invite create --org-id $ORG_ID --email lead@acme.com --role Admin

Sprint planning

# Create a sprint
alloy sprint create --project $PROJECT_ID --name "Sprint 12" \
  --start-date 2026-03-25 --end-date 2026-04-08 \
  --goal "Ship user authentication"

# Create tickets for the sprint
alloy ticket create --project $PROJECT_ID --title "Implement login endpoint" --priority high
alloy ticket create --project $PROJECT_ID --title "Add password reset flow" --priority medium
alloy ticket create --project $PROJECT_ID --title "Write auth integration tests" --priority medium

# Start the sprint
alloy sprint start $SPRINT_ID

# Check sprint status
alloy sprint list --project $PROJECT_ID

Time tracking for a week

# Set your default project
alloy project use BACK

# Log daily entries
alloy time log --ticket 42 --duration 120 --activity-type Coding --date 2026-03-24 --description "Auth middleware"
alloy time log --ticket 42 --duration 90 --activity-type Testing --date 2026-03-25 --description "Auth tests"
alloy time log --ticket 43 --duration 60 --activity-type CodeReview --date 2026-03-25 --description "PR review"
alloy time log --ticket 44 --duration 45 --activity-type Meeting --date 2026-03-26 --description "Sprint planning"
alloy time log --ticket 42 --duration 180 --activity-type Coding --date 2026-03-27 --description "Token refresh"

# Submit all entries
alloy time list --ticket 42 --format json | jq -r '.data[].id' | xargs -I{} alloy time submit {}

# Generate monthly report
alloy time report --period 2026-03

Bulk ticket updates with JSON output piping

# Close all done tickets
alloy ticket list --status done --format json | jq -r '.data[].id' | \
  xargs -I{} alloy ticket update {} --status cancelled

# Reassign all tickets from one user to another
alloy ticket list --assignee-id $OLD_USER --format json | jq -r '.data[].id' | \
  xargs -I{} alloy ticket update {} --assignee-id $NEW_USER

# Export all high-priority tickets
alloy ticket list --priority high --format json | jq '.data[] | {id, title, status}'

Shell Completions

Alloy can generate shell completion scripts for tab-completion of commands, subcommands, flags, and enum values.

alloy completions <SHELL>

Bash

Add to your ~/.bashrc:

# Generate and source completions
eval "$(alloy completions bash)"

Or install persistently:

# Create completions directory if needed
mkdir -p ~/.local/share/bash-completion/completions

# Generate the completion script
alloy completions bash > ~/.local/share/bash-completion/completions/alloy

# Reload your shell
source ~/.bashrc

Zsh

Add to your ~/.zshrc:

# Generate and source completions
eval "$(alloy completions zsh)"

Or install persistently:

# Ensure completions directory is in fpath (add to ~/.zshrc before compinit)
mkdir -p ~/.zfunc
echo 'fpath=(~/.zfunc $fpath)' >> ~/.zshrc

# Generate the completion script
alloy completions zsh > ~/.zfunc/_alloy

# Rebuild completion cache
rm -f ~/.zcompdump && compinit

Fish

# Generate and install completions
alloy completions fish > ~/.config/fish/completions/alloy.fish

Fish automatically loads completions from ~/.config/fish/completions/, so no additional configuration is needed.

Verifying Completions

After installation, restart your shell (or source the relevant config file) and test by typing:

alloy <TAB>

You should see all available subcommands (health, project, ticket, sprint, time, team, completions, etc.) as completion suggestions.

Alloy TUI Guide & Keybinding Cheat Sheet

The Alloy TUI is a terminal-based interface for managing projects, tickets, and sprints. It uses vim-style modal editing — if you know vim, you already know how to navigate.

Launching the TUI

# Default — connects to http://localhost:3000
cargo run --bin alloy-tui

# Custom API server
ALLOY_BASE_URL=https://api.example.com cargo run --bin alloy-tui

# Or export first
export ALLOY_BASE_URL=http://localhost:3000
cargo run --bin alloy-tui

If you have the alloy-tui binary on your PATH:

alloy-tui
ALLOY_BASE_URL=https://api.example.com alloy-tui

Configuration

Auto-Discover Behavior

On startup the TUI automatically discovers your organization:

1. If ALLOY_ORG_ID is set, that value is used directly.
2. Otherwise, once connected to the API, the TUI calls GET /api/v1/auth/me and extracts org_id from the response.
3. After org_id is resolved, projects, tickets, and labels are fetched automatically.

This means you can launch the TUI without any configuration beyond ALLOY_BASE_URL and a valid API key — the org is detected for you.

Modes

The TUI has four modes, displayed in the status bar with distinct colors.

If you are new to vim-style modes: you start in Normal mode. Press keys to navigate (they are not typed into a text field). Switch to Insert mode to type text, Command mode to enter commands, or Search mode to filter tickets. Press Esc to return to Normal.

Views

Ticket List

The default view. Shows all tickets in a table with columns for Key, Title, Status, Assignee, and Priority.

Ticket Detail

Full view of a single ticket: status, priority, assignee, reporter, sprint, timestamps, description (word-wrapped), and comments.

Sprint Board

Horizontal kanban board showing tickets grouped by status columns.

Open a sprint board with the :sprint <sprint-id> command.

Quick Actions

Available from Ticket List, Ticket Detail, and Sprint Board views.

Inside a popup:

The comment popup accepts free-text input. Type your comment and press Enter to submit or Esc to cancel.

Ticket Creation

Press n to open the ticket creation popup. It has two fields:

Use Tab to switch between the Title and Priority fields. In the Priority field, j/k cycle through options. Press Enter to create the ticket or Esc to cancel.

The ticket is created in the currently selected project. The reporter is set to the authenticated user automatically.

Label Management

Press l (or L on the sprint board) to open the label popup for the selected ticket. The popup lists all organization labels with a toggle indicator:

• ✓ label-name (#COLOR) — label is attached to the ticket
• label-name (#COLOR) — label is not attached

Navigate with j/k and press Enter to toggle a label on or off. Press Esc to close the popup.

Time Logging

Press t to open the time logging popup for the selected ticket. It has two fields:

Use Tab to switch between fields. The default activity type is Coding. Press Enter to submit or Esc to cancel. The time entry is logged for today’s date against the selected ticket.

Delete

Press d to delete the selected ticket. A confirmation popup appears with Cancel selected by default for safety. Select “Yes, delete” and press Enter to confirm.

If the ticket has dependents (comments, etc.), the simple delete returns a 409 Conflict. Use D instead for cascade delete:

1. A dry-run request previews what will be deleted (e.g., comment count).
2. A confirmation popup shows “Yes, delete ticket + N comments” and “Cancel”.
3. On confirmation the ticket and all dependents are removed.

After deletion the ticket is removed from the local list and the cursor adjusts automatically.

Burndown Chart

When viewing a sprint board, a burndown chart is displayed at the bottom showing sprint progress over time. The chart includes:

• Sprint date range (start to end)
• Total tickets vs completed/remaining count
• Completion percentage
• Progress sparkline

Press b to toggle the burndown chart on or off. It is shown by default when opening a sprint board.

Sprint Management

Sprint operations are available via command mode (:sprint).

Examples:

:sprint list
:sprint create Sprint-4 2026-04-01 2026-04-14
:sprint start abc123-def456
:sprint complete abc123-def456
:sprint abc123-def456

Command Mode

Press : to enter Command mode. Type a command and press Enter to execute.

Sort fields: priority, status, title, assignee Sort directions: asc (default), desc

Command mode helpers:

Search

Press / to enter Search mode. Type to filter tickets in real time.

• Matches against ticket key, title, and status (case-insensitive)
• Press Esc to stop searching (matches remain highlighted)
• Press n for next match, N for previous match (in Normal mode)
• Filtering respects active project and status filters

Complete Keybinding Reference

Normal Mode — Global

Normal Mode — Navigation

Normal Mode — Actions

Search Mode

Popup Controls

TUI Layout

┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│                      Main Content Area                           │
│                                                                  │
│   Ticket List ─────────────────────────────────────────────────  │
│   ┌──────────┬────────────────────┬────────────┬──────────────┐  │
│   │ Key      │ Title              │ Status     │ Priority     │  │
│   ├──────────┼────────────────────┼────────────┼──────────────┤  │
│   │ PROJ-1   │ Fix login bug      │ InProgress │ High         │  │
│   │ PROJ-2   │ Add dark mode      │ Todo       │ Medium       │  │
│   │ PROJ-3   │ Update docs        │ Done       │ Low          │  │
│   └──────────┴────────────────────┴────────────┴──────────────┘  │
│                                                                  │
│   — or —                                                         │
│                                                                  │
│   Ticket Detail ───────────────────────────────────────────────  │
│   ┌────────────────────────────────────────────────────────────┐ │
│   │ Status: InProgress   Priority: High                        │ │
│   │ Assignee: alice      Reporter: bob                         │ │
│   │ Sprint: Sprint 3     Created: 2026-03-01                   │ │
│   │                                                            │ │
│   │ Description                                                │ │
│   │ ────────────────────────────────────                       │ │
│   │ [scrollable content with word wrapping]                    │ │
│   │                                                            │ │
│   │ Comments                                                   │ │
│   │ ────────────────────────────────────                       │ │
│   │ alice (2026-03-02): Looks good to me                       │ │
│   └────────────────────────────────────────────────────────────┘ │
│                                                                  │
│   — or —                                                         │
│                                                                  │
│   Sprint Board (kanban) ───────────────────────────────────────  │
│   ┌───────────────┬───────────────┬───────────────┐              │
│   │ Todo (3)      │ InProgress (2)│ Done (4)      │              │
│   ├───────────────┼───────────────┼───────────────┤              │
│   │ PROJ-1: Fix   │ PROJ-3: API  │ PROJ-2: Docs  │              │
│   │ PROJ-4: Auth  │ PROJ-5: Test │ PROJ-6: Setup │              │
│   │ PROJ-7: UI    │              │ PROJ-8: CI    │              │
│   │               │              │ PROJ-9: Deps  │              │
│   └───────────────┴───────────────┴───────────────┘              │
│   ┌────────────── Burndown ──────────────────────┐               │
│   │ Sprint 3 (2026-03-01 → 2026-03-14)  67%     │               │
│   │ Total: 9  Done: 6  Remaining: 3             │               │
│   │ ▁▂▃▄▅▆▇█ progress sparkline                 │               │
│   └──────────────────────────────────────────────┘               │
│                                                                  │
├──────────────────────────────────────────────────────────────────┤
│ [NORMAL] Connected │ [PROJ] 2/15                    Status Bar   │
└──────────────────────────────────────────────────────────────────┘

The status bar shows:

• Mode indicator — current mode with colored background
• Connection status — whether the API is reachable
• Context info — varies by view:
  • Ticket List: project key and cursor position (e.g., [PROJ] 5/23)
  • Sprint Board: sprint name, date range, progress, and board position
  • Command/Search mode: the command or search buffer being typed

API Reference

Alloy exposes a REST API at http://localhost:3000 (default). When TLS is configured, the base URL becomes https://your-domain.com. All examples use curl with shell variables you can set once and reuse.

Common Setup

export BASE_URL="http://localhost:3000"  # or https://your-domain.com with TLS
export TOKEN="<your-access-token>"
export ORG_ID="<your-org-uuid>"
export PROJECT_ID="<your-project-uuid>"

Content Type

All request bodies are JSON. Set the header on every mutating request:

Content-Type: application/json

Authentication

Most endpoints require a Bearer token or API key in the Authorization header:

Authorization: Bearer $TOKEN

Public endpoints (no auth required): GET /health, POST /api/v1/auth/register, POST /api/v1/auth/login, GET /api/v1/onboard, POST /api/v1/onboard.

Roles and Permissions

Guide: Teams, Roles, and Permissions

Every organization member has one of five roles, listed from most to least privileged:

Permission Matrix

The table below shows the minimum role required for each operation. Any higher role also has access (e.g. Admin can do everything Member can). Read/list operations are available to all authenticated roles unless otherwise noted.

Project Membership (Reporter Scoping)

Reporters only see projects they are explicitly assigned to. When a Reporter calls GET /api/v1/projects, only assigned projects are returned. Calling GET /api/v1/projects/{id} or creating a ticket in an unassigned project returns 403.

Error Responses

All errors return a JSON body with this shape:

{
  "error": {
    "code": "not_found",
    "message": "Ticket not found",
    "details": []
  }
}

403 Forbidden

Returned when the authenticated user’s role is insufficient for the operation.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "requires Admin role or above",
    "details": []
  }
}

409 Conflict (Delete Guards)

Returned when deleting a resource that has dependents and cascade is not set. The details array lists each dependent type and its count.

{
  "error": {
    "code": "CONFLICT",
    "message": "Cannot delete project with existing dependents",
    "details": ["tickets: 5", "sprints: 2"]
  }
}

All DELETE endpoints that enforce delete guards accept these query parameters:

A cascade dry-run (?cascade=true&dry_run=true) returns 200 OK with a body listing what would be deleted. See each DELETE endpoint for its specific response shape.

Pagination

List endpoints use cursor-based pagination. Pass cursor and limit as query parameters. Responses include:

{
  "items": [],
  "next_cursor": "abc123",
  "has_more": true
}

Auth

Register

Create a new user account.

POST /api/v1/auth/register — no auth required

curl -s "$BASE_URL/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "password": "changeme123",
    "display_name": "Alice"
  }' | jq .

{
  "access_token": "eyJ...",
  "refresh_token": "def...",
  "user_id": "550e8400-...",
  "email": "alice@example.com",
  "display_name": "Alice"
}

Login

Authenticate an existing user.

POST /api/v1/auth/login — no auth required

curl -s "$BASE_URL/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "password": "changeme123"
  }' | jq .

{
  "access_token": "eyJ...",
  "refresh_token": "def...",
  "user_id": "550e8400-...",
  "email": "alice@example.com",
  "display_name": "Alice"
}

Refresh Token

Exchange a refresh token for new tokens.

POST /api/v1/auth/refresh

curl -s "$BASE_URL/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d "{\"refresh_token\": \"$REFRESH_TOKEN\"}" | jq .

{
  "access_token": "eyJ...",
  "refresh_token": "ghi...",
  "user_id": "550e8400-...",
  "email": "alice@example.com",
  "display_name": "Alice"
}

Logout

Revoke a refresh token.

POST /api/v1/auth/logout

curl -s -X POST "$BASE_URL/api/v1/auth/logout" \
  -H "Content-Type: application/json" \
  -d "{\"refresh_token\": \"$REFRESH_TOKEN\"}"

Returns 204 No Content on success.

Get Current User

Return the authenticated user’s profile and permissions.

GET /api/v1/auth/me — requires auth

curl -s "$BASE_URL/api/v1/auth/me" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "user_id": "550e8400-...",
  "org_id": "660e8400-...",
  "email": "alice@example.com",
  "role": "Owner",
  "scopes": "...",
  "allowed_project_ids": "..."
}

Create API Key

Generate a long-lived API key for programmatic access.

POST /api/v1/api-keys — requires auth

curl -s "$BASE_URL/api/v1/api-keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Key", "scopes": ["read", "write"]}' | jq .

{
  "id": "770e8400-...",
  "name": "CI Key",
  "key": "alloy_live_abc123...",
  "key_prefix": "alloy_live_...",
  "scopes": ["read", "write"],
  "project_ids": [],
  "created_at": "2026-03-28-...",
  "expires_at": null
}

List API Keys

GET /api/v1/api-keys — requires auth

curl -s "$BASE_URL/api/v1/api-keys" \
  -H "Authorization: Bearer $TOKEN" | jq .

[
  {
    "id": "770e8400-...",
    "name": "CI Key",
    "key_prefix": "alloy_live_...",
    "scopes": ["read", "write"],
    "project_ids": [],
    "created_at": "2026-03-28-...",
    "last_used_at": null,
    "expires_at": null
  }
]

Delete API Key

DELETE /api/v1/api-keys/{id} — requires auth

curl -s -X DELETE "$BASE_URL/api/v1/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content.

Onboarding

Check Onboarding Status

GET /api/v1/onboard — no auth required

curl -s "$BASE_URL/api/v1/onboard" | jq .

Returns {"needs_onboarding": true} when no users exist, or {"needs_onboarding": false} otherwise.

Run Onboarding

Create the first organization and admin user. Only available when no orgs exist.

POST /api/v1/onboard — no auth required

curl -s "$BASE_URL/api/v1/onboard" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "changeme123",
    "org_name": "Acme Corp",
    "org_slug": "acme"
  }' | jq .

Returns org_id, user_id, email, api_key, and api_key_prefix on success. Returns 409 Conflict if onboarding was already completed.

Orgs

Create Organization

POST /api/v1/orgs — requires auth

curl -s "$BASE_URL/api/v1/orgs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "slug": "acme"}' | jq .

{
  "id": "660e8400-...",
  "name": "Acme Corp",
  "slug": "acme",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

List Organizations

GET /api/v1/orgs — requires auth

curl -s "$BASE_URL/api/v1/orgs" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "660e8400-...",
      "name": "...",
      "slug": "...",
      "created_at": "2026-03-28-...",
      "updated_at": "2026-03-28-..."
    }
  ]
}

Add Member to Organization

POST /api/v1/orgs/{id}/members — requires auth

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/members" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"user_id\": \"$USER_ID\", \"role\": \"member\"}" | jq .

Returns the membership object with user_id, org_id, role, and joined_at. Returns 409 Conflict if the user is already a member.

List Organization Members

GET /api/v1/orgs/{id}/members — requires auth

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/members" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "user_id": "550e8400-...",
      "display_name": "Alice",
      "email": "alice@example.com",
      "role": "Owner",
      "joined_at": "2026-03-28-..."
    }
  ]
}

Create Invite

Generate an invite link to join an organization.

POST /api/v1/orgs/{org_id}/invites — requires auth

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/invites" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "bob@example.com", "role": "member"}' | jq .

Returns the invite object with id, invite_code, invite_link, email, role, and expires_at.

List Invites

GET /api/v1/orgs/{org_id}/invites — requires auth

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/invites" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns an array of invite objects for the organization.

Revoke Invite

DELETE /api/v1/orgs/{org_id}/invites/{id} — requires auth

curl -s -X DELETE "$BASE_URL/api/v1/orgs/$ORG_ID/invites/$INVITE_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content.

Projects

Guide: Projects and Tickets

Create Project

POST /api/v1/projects — requires auth

curl -s "$BASE_URL/api/v1/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"org_id\": \"$ORG_ID\",
    \"key\": \"PROJ\",
    \"name\": \"My Project\",
    \"description\": \"A sample project\"
  }" | jq .

{
  "id": "990e8400-...",
  "org_id": "660e8400-...",
  "team_id": null,
  "workflow_id": null,
  "key": "PROJ",
  "name": "My Project",
  "description": "A sample project",
  "ticket_counter": 0,
  "capitalization_type": null,
  "development_phase": null,
  "cost_center_id": null,
  "amortization_months": null,
  "budget_cents": null,
  "budget_period": null,
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

List Projects

GET /api/v1/projects?org_id={org_id} — requires auth

curl -s "$BASE_URL/api/v1/projects?org_id=$ORG_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "990e8400-...",
      "org_id": "660e8400-...",
      "key": "PROJ",
      "name": "My Project",
      "description": "A sample project",
      "ticket_counter": 0,
      "created_at": "2026-03-28-...",
      "updated_at": "2026-03-28-..."
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Get Project by ID

GET /api/v1/projects/{id} — requires auth

curl -s "$BASE_URL/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a single ProjectResponse.

Get Project by Key

GET /api/v1/projects/key/{key} — requires auth

curl -s "$BASE_URL/api/v1/projects/key/PROJ?org_id=$ORG_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a single ProjectResponse.

Update Project

PATCH /api/v1/projects/{id} — requires auth

curl -s -X PATCH "$BASE_URL/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed Project"}' | jq .

Returns the updated ProjectResponse.

Delete Project

DELETE /api/v1/projects/{id} — requires Admin

Returns 204 No Content if the project has no dependents.

Returns 409 Conflict if the project has tickets or sprints. Use ?cascade=true to delete all dependents, or ?cascade=true&dry_run=true to preview what would be deleted.

Cascade dry-run response (?cascade=true&dry_run=true):

{
  "project_id": "...",
  "dependents": {
    "tickets": 5,
    "sprints": 2,
    "comments": 12
  }
}

409 response (no cascade, has dependents):

{
  "error": {
    "code": "CONFLICT",
    "message": "Cannot delete project with existing dependents",
    "details": ["tickets: 5", "sprints: 2"]
  }
}

curl -s -X DELETE "$BASE_URL/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content on success.

Project Members

Guide: Teams, Roles, and Permissions

Manage which users are assigned to a project. Reporters can only access projects they are members of. Other roles (Member and above) see all projects regardless of membership.

Add Project Member

POST /api/v1/projects/{project_id}/members — requires Member

{
  "project_id": "...",
  "user_id": "...",
  "created_at": "..."
}

Returns 201 Created.

List Project Members

GET /api/v1/projects/{project_id}/members — requires auth

Returns an array of project membership objects:

[
  {
    "project_id": "...",
    "user_id": "...",
    "created_at": "..."
  }
]

Remove Project Member

DELETE /api/v1/projects/{project_id}/members/{user_id} — requires Member

Returns 204 No Content.

Tickets

Guides: Projects and Tickets | Workflows and Statuses

Create Ticket

POST /api/v1/projects/{project_id}/tickets — requires auth

curl -s "$BASE_URL/api/v1/projects/$PROJECT_ID/tickets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"title\": \"Fix login bug\",
    \"description\": \"Users can't log in with SSO\",
    \"priority\": \"High\"
  }" | jq .

{
  "id": "aa0e8400-...",
  "project_id": "990e8400-...",
  "ticket_number": 1,
  "title": "Fix login bug",
  "description": "Users can't log in with SSO",
  "status": "Backlog",
  "priority": "High",
  "assignee_id": null,
  "reporter_id": "550e8400-...",
  "sprint_id": null,
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

List Tickets

GET /api/v1/projects/{project_id}/tickets — requires auth

curl -s "$BASE_URL/api/v1/projects/$PROJECT_ID/tickets?status=Backlog" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "aa0e8400-...",
      "project_id": "990e8400-...",
      "ticket_number": 1,
      "title": "Fix login bug",
      "status": "Backlog",
      "priority": "High",
      "created_at": "2026-03-28-...",
      "updated_at": "2026-03-28-..."
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Get Ticket

GET /api/v1/tickets/{id} — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a single TicketResponse.

Resolve Ticket Reference

Look up a ticket by UUID, key-number (e.g. PROJ-42), or bare number.

GET /api/v1/tickets/resolve?ref={ref} — requires auth

curl -s "$BASE_URL/api/v1/tickets/resolve?ref=PROJ-1&org_id=$ORG_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "ticket": {
    "id": "aa0e8400-...",
    "ticket_number": 1,
    "title": "Fix login bug"
  },
  "suggestions": []
}

Update Ticket

PATCH /api/v1/tickets/{id} — requires auth

curl -s -X PATCH "$BASE_URL/api/v1/tickets/$TICKET_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "InProgress", "priority": "Critical"}' | jq .

Returns the updated TicketResponse.

Delete Ticket

DELETE /api/v1/tickets/{id} — requires Admin

Returns 204 No Content if the ticket has no dependents.

Returns 409 Conflict if the ticket has comments. Use ?cascade=true to delete all dependents, or ?cascade=true&dry_run=true to preview.

Cascade dry-run response (?cascade=true&dry_run=true):

{
  "ticket_id": "...",
  "dependents": {
    "comments": 3
  }
}

409 response (no cascade, has dependents):

{
  "error": {
    "code": "CONFLICT",
    "message": "Cannot delete ticket with existing dependents",
    "details": ["comments: 3"]
  }
}

Batch Update Tickets

Apply the same field updates to multiple tickets at once. Accepts an array of ticket IDs and the fields to update. Returns the count of updated tickets. Requires Member role.

POST /api/v1/tickets/batch-update — requires Member

curl -s -X POST "$BASE_URL/api/v1/tickets/batch-update" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ticket_ids":["'"$TICKET_ID"'"],"status":"Done"}'

{
  "updated": 1
}

Batch Delete Tickets

Delete multiple tickets at once. Supports cascade deletion (removes comments) and dry-run mode (reports what would happen without deleting). Tickets with dependents are blocked unless cascade is true. Requires Admin role.

POST /api/v1/tickets/batch-delete — requires Admin

curl -s -X POST "$BASE_URL/api/v1/tickets/batch-delete" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ticket_ids":["'"$TICKET_ID"'"],"cascade":true,"dry_run":true}'

{
  "deleted": ["..."],
  "blocked": []
}

When tickets have dependents and cascade is false, they appear in blocked:

{
  "deleted": [],
  "blocked": [
    {
      "id": "...",
      "dependents": {
        "comments": 3
      }
    }
  ]
}

Transition Ticket Status

Transition a ticket through a workflow. Validates the transition against the workflow’s rules and enforcement mode (see Enforcement Modes).

POST /api/v1/tickets/{id}/transition — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/transition" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to_status": "InReview"}' | jq .

Returns the updated TicketResponse.

Get Available Transitions

GET /api/v1/tickets/{id}/available-transitions — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/available-transitions" \
  -H "Authorization: Bearer $TOKEN" | jq .

Get Ticket Activity

GET /api/v1/tickets/{ticket_id}/activity — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/activity" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "type": "...",
      "actor": "550e8400-...",
      "timestamp": "2026-03-28-...",
      "payload": {
        "audit_log_id": "...",
        "action": "...",
        "entity_type": "...",
        "changes": [
          {
            "field": "...",
            "old": "...",
            "new": "..."
          }
        ]
      }
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Comments

Guide: Projects and Tickets

Create Comment

POST /api/v1/tickets/{ticket_id}/comments — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/comments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"body\": \"This needs investigation.\"
  }" | jq .

{
  "id": "bb0e8400-...",
  "ticket_id": "aa0e8400-...",
  "author_id": "550e8400-...",
  "body": "This needs investigation.",
  "parent_comment_id": null,
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

List Comments

GET /api/v1/tickets/{ticket_id}/comments — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/comments" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "bb0e8400-...",
      "ticket_id": "aa0e8400-...",
      "author_id": "550e8400-...",
      "body": "This needs investigation.",
      "parent_comment_id": null,
      "created_at": "2026-03-28-...",
      "updated_at": "2026-03-28-..."
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Get Comment

GET /api/v1/comments/{id} — requires auth

curl -s "$BASE_URL/api/v1/comments/$COMMENT_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "id": "bb0e8400-...",
  "ticket_id": "aa0e8400-...",
  "author_id": "550e8400-...",
  "body": "This needs investigation.",
  "parent_comment_id": null,
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Update Comment

PATCH /api/v1/comments/{id} — requires auth

curl -s -X PATCH "$BASE_URL/api/v1/comments/$COMMENT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body": "Updated comment text."}' | jq .

{
  "id": "bb0e8400-...",
  "ticket_id": "aa0e8400-...",
  "author_id": "550e8400-...",
  "body": "Updated comment text.",
  "parent_comment_id": null,
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Delete Comment

DELETE /api/v1/comments/{id} — requires Author or Admin

Only the comment author or an Admin+ can delete a comment. Returns 403 if another non-admin user attempts to delete.

curl -s -X DELETE "$BASE_URL/api/v1/comments/$COMMENT_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content.

Labels

Guide: Labels, Tags, and Organization

Create Label

POST /api/v1/orgs/{org_id}/labels — requires auth

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/labels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "bug", "color": "#FF0000"}' | jq .

{
  "id": "cc0e8400-...",
  "org_id": "660e8400-...",
  "name": "bug",
  "color": "#FF0000",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

List Labels

GET /api/v1/orgs/{org_id}/labels — requires auth

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/labels" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "cc0e8400-...",
      "org_id": "660e8400-...",
      "name": "bug",
      "color": "#FF0000",
      "created_at": "2026-03-28-...",
      "updated_at": "2026-03-28-..."
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Get Label

GET /api/v1/labels/{id} — requires auth

curl -s "$BASE_URL/api/v1/labels/$LABEL_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "id": "cc0e8400-...",
  "org_id": "660e8400-...",
  "name": "bug",
  "color": "#FF0000",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Update Label

PATCH /api/v1/labels/{id} — requires auth

curl -s -X PATCH "$BASE_URL/api/v1/labels/$LABEL_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"color": "#00FF00"}' | jq .

{
  "id": "cc0e8400-...",
  "org_id": "660e8400-...",
  "name": "bug",
  "color": "#00FF00",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Batch Assign Label

Assign a label to multiple tickets at once. The label is applied to each ticket in the list. Idempotent — assigning a label that is already present has no effect. Requires Member role.

POST /api/v1/labels/{id}/batch-assign — requires Member

curl -s -X POST "$BASE_URL/api/v1/labels/$LABEL_ID/batch-assign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ticket_ids":["'"$TICKET_ID"'"]}'

{
  "assigned": 1
}

Delete Label

DELETE /api/v1/labels/{id} — requires auth

Returns 204 No Content if the label has no dependents.

Returns 409 Conflict if tickets are using this label. Use ?cascade=true to remove all ticket-label associations, or ?cascade=true&dry_run=true to preview.

Cascade dry-run response (?cascade=true&dry_run=true):

{
  "label_id": "...",
  "dependents": {
    "tickets": 4
  }
}

curl -s -X DELETE "$BASE_URL/api/v1/labels/$LABEL_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content on success.

Set Ticket Labels

Replace all labels on a ticket.

POST /api/v1/tickets/{ticket_id}/labels — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/labels" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"label_ids\": [\"$LABEL_ID\"]}" | jq .

[
  {
    "id": "cc0e8400-...",
    "org_id": "660e8400-...",
    "name": "...",
    "color": "...",
    "created_at": "2026-03-28-...",
    "updated_at": "2026-03-28-..."
  }
]

List Ticket Labels

GET /api/v1/tickets/{ticket_id}/labels — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/labels" \
  -H "Authorization: Bearer $TOKEN" | jq .

[
  {
    "id": "cc0e8400-...",
    "org_id": "660e8400-...",
    "name": "...",
    "color": "...",
    "created_at": "2026-03-28-...",
    "updated_at": "2026-03-28-..."
  }
]

Add Label to Ticket

POST /api/v1/tickets/{ticket_id}/labels/{label_id} — requires auth

curl -s -X POST "$BASE_URL/api/v1/tickets/$TICKET_ID/labels/$LABEL_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

[
  {
    "id": "cc0e8400-...",
    "org_id": "660e8400-...",
    "name": "...",
    "color": "...",
    "created_at": "2026-03-28-...",
    "updated_at": "2026-03-28-..."
  }
]

Remove Label from Ticket

DELETE /api/v1/tickets/{ticket_id}/labels/{label_id} — requires auth

curl -s -X DELETE "$BASE_URL/api/v1/tickets/$TICKET_ID/labels/$LABEL_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content.

Sprints

Guide: Sprints and Boards

Create Sprint

POST /api/v1/projects/{project_id}/sprints — requires auth

curl -s "$BASE_URL/api/v1/projects/$PROJECT_ID/sprints" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sprint 1",
    "goal": "Complete MVP",
    "start_date": "2026-03-28",
    "end_date": "2026-04-11"
  }' | jq .

{
  "id": "dd0e8400-...",
  "project_id": "990e8400-...",
  "name": "Sprint 1",
  "goal": "Complete MVP",
  "start_date": "2026-03-28",
  "end_date": "2026-04-11",
  "status": "Planned",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

List Sprints

GET /api/v1/projects/{project_id}/sprints — requires auth

curl -s "$BASE_URL/api/v1/projects/$PROJECT_ID/sprints" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "dd0e8400-...",
      "project_id": "990e8400-...",
      "name": "Sprint 1",
      "goal": "Complete MVP",
      "start_date": "2026-03-28",
      "end_date": "2026-04-11",
      "status": "Planned",
      "created_at": "2026-03-28-...",
      "updated_at": "2026-03-28-..."
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Get Sprint

GET /api/v1/sprints/{id} — requires auth

curl -s "$BASE_URL/api/v1/sprints/$SPRINT_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "id": "dd0e8400-...",
  "project_id": "990e8400-...",
  "name": "Sprint 1",
  "goal": "Complete MVP",
  "start_date": "2026-03-28",
  "end_date": "2026-04-11",
  "status": "Planned",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Update Sprint

PATCH /api/v1/sprints/{id} — requires auth

curl -s -X PATCH "$BASE_URL/api/v1/sprints/$SPRINT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"goal": "Ship auth and tickets"}' | jq .

{
  "id": "dd0e8400-...",
  "project_id": "990e8400-...",
  "name": "Sprint 1",
  "goal": "Ship auth and tickets",
  "start_date": "2026-03-28",
  "end_date": "2026-04-11",
  "status": "Planned",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Start Sprint

Transition a sprint from Planned to Active.

POST /api/v1/sprints/{id}/start — requires auth

curl -s -X POST "$BASE_URL/api/v1/sprints/$SPRINT_ID/start" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "id": "dd0e8400-...",
  "project_id": "990e8400-...",
  "name": "...",
  "goal": "...",
  "start_date": "...",
  "end_date": "...",
  "status": "...",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Complete Sprint

Transition a sprint from Active to Completed.

POST /api/v1/sprints/{id}/complete — requires auth

curl -s -X POST "$BASE_URL/api/v1/sprints/$SPRINT_ID/complete" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "id": "dd0e8400-...",
  "project_id": "990e8400-...",
  "name": "...",
  "goal": "...",
  "start_date": "...",
  "end_date": "...",
  "status": "...",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Batch Assign Tickets to Sprint

Assign multiple tickets to a sprint at once. Requires Member role.

POST /api/v1/sprints/{id}/batch-assign — requires Member

curl -s -X POST "$BASE_URL/api/v1/sprints/$SPRINT_ID/batch-assign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ticket_ids":["'"$TICKET_ID"'"]}'

{
  "assigned": 1
}

Delete Sprint

DELETE /api/v1/sprints/{id} — requires Admin

Returns 204 No Content if the sprint has no dependents.

Returns 409 Conflict if the sprint has tickets. Use ?cascade=true to delete all dependents, or ?cascade=true&dry_run=true to preview.

Cascade dry-run response (?cascade=true&dry_run=true):

{
  "sprint_id": "...",
  "dependents": {
    "tickets": 8
  }
}

409 response (no cascade, has dependents):

{
  "error": {
    "code": "CONFLICT",
    "message": "Cannot delete sprint with existing dependents",
    "details": ["tickets: 8"]
  }
}

Get Sprint Board

GET /api/v1/sprints/{id}/board — requires auth

curl -s "$BASE_URL/api/v1/sprints/$SPRINT_ID/board" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "sprint": {
    "id": "dd0e8400-...",
    "project_id": "990e8400-...",
    "name": "...",
    "goal": "...",
    "start_date": "...",
    "end_date": "...",
    "status": "...",
    "created_at": "2026-03-28-...",
    "updated_at": "2026-03-28-..."
  },
  "columns": [
    {
      "status": "...",
      "tickets": []
    },
    {
      "status": "...",
      "tickets": []
    },
    {
      "status": "...",
      "tickets": []
    }
  ]
}

Get Sprint Burndown

GET /api/v1/sprints/{id}/burndown — requires auth

curl -s "$BASE_URL/api/v1/sprints/$SPRINT_ID/burndown" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns sprint_id and data array with daily entries containing date, total_tickets, completed_tickets, and remaining_tickets.

Workflows

Guide: Workflows and Statuses

Ticket statuses are workflow-defined — there are no hard-coded statuses. Each workflow declares its own set of statuses with categories (todo, in_progress, done, cancelled) and the allowed transitions between them. Every organization gets a “Default” workflow on creation. Projects can be assigned a workflow via PATCH /api/v1/projects/{id}.

Enforcement Modes

Workflows have an enforcement field that controls what happens when a ticket transition violates the workflow’s transition rules:

When enforcement is strict and a transition is not allowed, the API returns:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "transition from 'Coding' to 'Shipped' is not allowed by workflow 'Kanban'",
    "details": []
  }
}

When enforcement is warn and a transition is not allowed, the transition succeeds but the response includes a warning:

{
  "ticket": { "id": "...", "status": "Done" },
  "warning": "transition from 'Todo' to 'Done' is not allowed by workflow 'Simple Flow', but enforcement is set to warn"
}

Create Workflow

POST /api/v1/orgs/{org_id}/workflows — requires Admin

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/workflows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Simple Flow",
    "statuses": [
      {"name": "Todo", "category": "todo"},
      {"name": "InProgress", "category": "in_progress"},
      {"name": "Done", "category": "done"}
    ],
    "transitions": [
      {"from": "Todo", "to": "InProgress"},
      {"from": "InProgress", "to": "Done"}
    ]
  }' | jq .

{
  "id": "ee0e8400-...",
  "org_id": "660e8400-...",
  "name": "Simple Flow",
  "statuses": [
    {"name": "Todo", "category": "todo"},
    {"name": "InProgress", "category": "in_progress"},
    {"name": "Done", "category": "done"}
  ],
  "transitions": [
    {"from": "Todo", "to": "InProgress"},
    {"from": "InProgress", "to": "Done"}
  ],
  "enforcement": "none",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

List Workflows

GET /api/v1/orgs/{org_id}/workflows — requires auth

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/workflows" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "...",
      "org_id": "...",
      "name": "...",
      "statuses": [
        {"name": "...", "category": "..."}
      ],
      "transitions": [
        {"from": "...", "to": "..."}
      ],
      "enforcement": "...",
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Get Workflow

GET /api/v1/workflows/{id} — requires auth

curl -s "$BASE_URL/api/v1/workflows/$WORKFLOW_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "id": "ee0e8400-...",
  "org_id": "660e8400-...",
  "name": "Simple Flow",
  "statuses": [
    {"name": "Todo", "category": "todo"},
    {"name": "InProgress", "category": "in_progress"},
    {"name": "Done", "category": "done"}
  ],
  "transitions": [
    {"from": "Todo", "to": "InProgress"},
    {"from": "InProgress", "to": "Done"}
  ],
  "enforcement": "...",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Update Workflow

PATCH /api/v1/workflows/{id} — requires Admin

curl -s -X PATCH "$BASE_URL/api/v1/workflows/$WORKFLOW_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Flow"}' | jq .

{
  "id": "ee0e8400-...",
  "org_id": "660e8400-...",
  "name": "Updated Flow",
  "statuses": [
    {"name": "Todo", "category": "todo"},
    {"name": "InProgress", "category": "in_progress"},
    {"name": "Done", "category": "done"}
  ],
  "transitions": [
    {"from": "Todo", "to": "InProgress"},
    {"from": "InProgress", "to": "Done"}
  ],
  "enforcement": "...",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Delete Workflow

DELETE /api/v1/workflows/{id} — requires Admin

Returns 204 No Content if the workflow has no dependents.

Returns 409 Conflict if any projects are using this workflow:

{
  "error": {
    "code": "CONFLICT",
    "message": "Cannot delete workflow with existing dependents",
    "details": ["projects: 3"]
  }
}

Note: Unlike other DELETE endpoints, workflow deletion does not support cascade or dry_run parameters. Unassign the workflow from all projects before deleting.

curl -s -X DELETE "$BASE_URL/api/v1/workflows/$WORKFLOW_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content on success.

Transition Ticket

Move a ticket to a new status. If a workflow is assigned to the project, the transition is validated against the workflow’s rules and enforcement mode.

POST /api/v1/tickets/{id}/transition — requires auth

curl -s -X POST "$BASE_URL/api/v1/tickets/$TICKET_ID/transition" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to_status": "InProgress"}' | jq .

Returns the updated TicketResponse.

{
  "id": "aa0e8400-...",
  "project_id": "990e8400-...",
  "title": "Fix login bug",
  "status": "InProgress",
  "priority": "High",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Get Available Transitions

List the statuses a ticket can transition to from its current status.

GET /api/v1/tickets/{id}/transitions — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/transitions" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "current_status": "...",
  "available": [
    {
      "name": "...",
      "category": "..."
    }
  ]
}

Batch Transition Tickets

Transition multiple tickets to the same target status in one call. Each ticket is validated individually against its project’s workflow. Returns per-ticket results so callers can see which succeeded and which failed. Useful for sprint completion (move all tickets to Done).

POST /api/v1/tickets/batch-transition — requires auth

curl -s -X POST "$BASE_URL/api/v1/tickets/batch-transition" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ticket_ids":["'"$TICKET_ID"'"],"to_status":"Done"}'

{
  "succeeded": [
    {
      "id": "...",
      "status": "Done"
    }
  ],
  "failed": []
}

When a transition fails for a ticket (e.g., invalid workflow transition in strict mode, or ticket not found), it appears in the failed array with a reason:

{
  "succeeded": [],
  "failed": [
    {
      "id": "...",
      "reason": "not found: ticket ..."
    }
  ]
}

Time Entries

Guide: Time Tracking and Finance

Create Time Entry

POST /api/v1/time-entries — requires auth

curl -s "$BASE_URL/api/v1/time-entries" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"user_id\": \"$USER_ID\",
    \"ticket_id\": \"$TICKET_ID\",
    \"project_id\": \"$PROJECT_ID\",
    \"date\": \"2026-03-28\",
    \"duration_minutes\": 120,
    \"description\": \"Investigated SSO bug\",
    \"activity_type\": \"Coding\"
  }" | jq .

{
  "id": "ff0e8400-...",
  "user_id": "550e8400-...",
  "ticket_id": "aa0e8400-...",
  "project_id": "990e8400-...",
  "date": "...",
  "duration_minutes": 120,
  "description": "...",
  "activity_type": "...",
  "status": "...",
  "approved_by": null,
  "approved_at": null,
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Get Time Entry

GET /api/v1/time-entries/{id} — requires auth

curl -s "$BASE_URL/api/v1/time-entries/$TIME_ENTRY_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "id": "ff0e8400-...",
  "user_id": "550e8400-...",
  "ticket_id": "aa0e8400-...",
  "project_id": "990e8400-...",
  "date": "...",
  "duration_minutes": 120,
  "description": "...",
  "activity_type": "...",
  "status": "...",
  "approved_by": null,
  "approved_at": null,
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

List Time Entries by Ticket

GET /api/v1/tickets/{ticket_id}/time-entries — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/time-entries" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a paginated list of TimeEntryResponse objects.

List Time Entries by User

GET /api/v1/users/{user_id}/time-entries — requires auth

curl -s "$BASE_URL/api/v1/users/$USER_ID/time-entries" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a paginated list of TimeEntryResponse objects.

Update Time Entry

PATCH /api/v1/time-entries/{id} — requires auth

curl -s -X PATCH "$BASE_URL/api/v1/time-entries/$TIME_ENTRY_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"duration_minutes": 180}' | jq .

Returns the updated TimeEntryResponse.

Delete Time Entry

DELETE /api/v1/time-entries/{id} — requires auth

curl -s -X DELETE "$BASE_URL/api/v1/time-entries/$TIME_ENTRY_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content on success.

Submit Time Entry

POST /api/v1/time-entries/{id}/submit — requires auth

Transitions a time entry from Draft to Submitted status.

curl -s -X POST "$BASE_URL/api/v1/time-entries/$TIME_ENTRY_ID/submit" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns the updated TimeEntryResponse with "status": "Submitted".

Approve Time Entry

POST /api/v1/time-entries/{id}/approve — requires auth

Transitions a time entry from Submitted to Approved status.

curl -s -X POST "$BASE_URL/api/v1/time-entries/$TIME_ENTRY_ID/approve" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns the updated TimeEntryResponse with "status": "Approved", approved_by, and approved_at populated.

List Submitted Time Entries

GET /api/v1/time-entries/submitted — requires auth

Returns all time entries with Submitted status, typically used by managers for approval workflows.

curl -s "$BASE_URL/api/v1/time-entries/submitted" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns an array of TimeEntryResponse objects.

Labor Rates

Guide: Time Tracking and Finance

Labor rates define the loaded cost rate per user per org, used for capitalization reporting. All labor rate endpoints require Admin or Owner role.

Create Labor Rate

POST /api/v1/labor-rates — requires auth (Admin/Owner)

curl -s "$BASE_URL/api/v1/labor-rates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"user_id\": \"$USER_ID\",
    \"org_id\": \"$ORG_ID\",
    \"loaded_rate_cents\": 15000,
    \"effective_date\": \"2026-01-01\"
  }" | jq .

{
  "id": "bb0e8400-...",
  "user_id": "550e8400-...",
  "org_id": "660e8400-...",
  "loaded_rate_cents": 15000,
  "effective_date": "2026-01-01",
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Get Labor Rate

GET /api/v1/labor-rates/{id} — requires auth (Admin/Owner)

curl -s "$BASE_URL/api/v1/labor-rates/$LABOR_RATE_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a UserLaborRateResponse.

Get Current Labor Rate

GET /api/v1/users/{user_id}/orgs/{org_id}/labor-rates/current — requires auth (Admin/Owner)

Returns the most recent labor rate by effective date for the given user and org.

curl -s "$BASE_URL/api/v1/users/$USER_ID/orgs/$ORG_ID/labor-rates/current" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a UserLaborRateResponse.

List Labor Rates

GET /api/v1/users/{user_id}/orgs/{org_id}/labor-rates — requires auth (Admin/Owner)

curl -s "$BASE_URL/api/v1/users/$USER_ID/orgs/$ORG_ID/labor-rates" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a paginated list of UserLaborRateResponse objects.

Entity Tags

Guide: Labels, Tags, and Organization

Tags are arbitrary key-value pairs attached to entities (projects, tickets, users, teams, time entries). They enable flexible metadata and filtering.

Set Tags

PUT /api/v1/orgs/{org_id}/{entity_type}/{entity_id}/tags — requires auth

Sets or upserts tags on an entity. If a tag key already exists, its value is updated.

curl -s -X PUT "$BASE_URL/api/v1/orgs/$ORG_ID/project/$PROJECT_ID/tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": [
      {"key": "department", "value": "engineering"},
      {"key": "environment", "value": "production"}
    ]
  }' | jq .

[
  {
    "id": "...",
    "org_id": "...",
    "entity_type": "project",
    "entity_id": "...",
    "key": "department",
    "value": "engineering",
    "created_at": "...",
    "updated_at": "..."
  },
  {
    "id": "...",
    "org_id": "...",
    "entity_type": "project",
    "entity_id": "...",
    "key": "environment",
    "value": "production",
    "created_at": "...",
    "updated_at": "..."
  }
]

Get Tags

GET /api/v1/orgs/{org_id}/{entity_type}/{entity_id}/tags — requires auth

Returns all tags for an entity.

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/project/$PROJECT_ID/tags" \
  -H "Authorization: Bearer $TOKEN" | jq .

[
  {
    "id": "...",
    "org_id": "...",
    "entity_type": "project",
    "entity_id": "...",
    "key": "department",
    "value": "engineering",
    "created_at": "...",
    "updated_at": "..."
  }
]

Delete Tag

DELETE /api/v1/orgs/{org_id}/{entity_type}/{entity_id}/tags/{key} — requires auth

Removes a single tag by key from an entity.

curl -s -X DELETE "$BASE_URL/api/v1/orgs/$ORG_ID/project/$PROJECT_ID/tags/environment" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content.

Search by Tag

GET /api/v1/orgs/{org_id}/tags/search — requires auth

Finds all entities with a given tag key-value pair. Returns paginated results.

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/tags/search?key=department&value=engineering" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "items": [
    {
      "id": "...",
      "org_id": "...",
      "entity_type": "project",
      "entity_id": "...",
      "key": "department",
      "value": "engineering",
      "created_at": "...",
      "updated_at": "..."
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Capitalization Reports

Guide: Time Tracking and Finance

Generate capitalization reports for software cost accounting (ASC 350-40 / IAS 38). Reports aggregate approved time entries with labor rates by project and activity type.

Get Capitalization Report

GET /api/v1/reports/capitalization — requires auth

Default (flat) response:

curl -s "$BASE_URL/api/v1/reports/capitalization?period=2026-03" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns {"period": "2026-03", "projects": [...]} where each project includes project_id, project_key, project_name, capitalization_type, development_phase, cost_center_id, total_hours, total_amount_cents, and a breakdown array of {activity_type, hours, amount_cents}.

With budget fields — add include_budget=true to include budget_cents, budget_period, spent_cents, budget_remaining_cents, and budget_utilization_pct on each project entry.

Grouped by team — add group_by=team to return {"period": "...", "teams": [{team_id, team_name, total_hours, total_amount_cents, projects}]}.

Grouped by user — add group_by=user to return {"period": "...", "users": [{user_id, display_name, total_hours, total_amount_cents, projects}]}.

Filter by tag — add tag=department:engineering to only include projects with that tag.

Export Capitalization Report (CSV)

GET /api/v1/reports/capitalization/export — requires auth

Supports all the same query parameters as the JSON endpoint above.

curl -s "$BASE_URL/api/v1/reports/capitalization/export?period=2026-03" \
  -H "Authorization: Bearer $TOKEN" -o report.csv

Returns a CSV file with header: Period,Project,ProjectKey,Employee,Department,CostCenter,Hours,ActivityType,Phase,CapExOpEx,LoadedRate,Amount,Team,Tags,BudgetCents,SpentCents,Utilization

Data Export & Import

Export complete project data as portable JSON or SQLite, or import data from an Alloy export to restore or migrate between instances. Relationships use human-readable keys (emails, project keys, label names) instead of UUIDs, making exports portable across Alloy instances.

Export Data

GET /api/v1/export — requires auth

curl -s "$BASE_URL/api/v1/export?org_id=$ORG_ID" \
  -H "Authorization: Bearer $TOKEN"

{
  "version": 1,
  "source": "alloy",
  "exported_at": "...",
  "projects": "...",
  "labels": "...",
  "workflows": "...",
  "users": "..."
}

Filter by project key — append &project=KEY to export a single project:

GET /api/v1/export?org_id=<ORG_ID>&project=DEMO

Export as SQLite — append &format=sqlite to download a self-contained SQLite database:

curl -s "$BASE_URL/api/v1/export?org_id=$ORG_ID&format=sqlite" \
  -H "Authorization: Bearer $TOKEN" -o alloy-export.db

The SQLite file contains tables: export_meta, users, labels, workflows, projects, project_members, sprints, tickets, ticket_labels, comments, time_entries. It can be opened and queried with any SQLite client.

Import Data

POST /api/v1/import — requires auth

Accepts an AlloyExport JSON body (as produced by the export endpoint) and creates all entities in the authenticated user’s organization, preserving relationships. Users and workflows are resolved by email/name to avoid duplicates. Returns a summary of created entities.

curl -s -X POST "$BASE_URL/api/v1/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":1,"source":"alloy","exported_at":"2026-01-01T00:00:00Z","projects":[],"labels":[],"workflows":[],"users":[]}'

{
  "status": "ok",
  "summary": {
    "users_created": 0,
    "workflows_created": 0,
    "labels_created": 0,
    "projects_created": 0,
    "sprints_created": 0,
    "tickets_created": 0,
    "comments_created": 0,
    "time_entries_created": 0
  }
}

With a file — for larger exports, use a file reference:

curl -s -X POST "$BASE_URL/api/v1/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @alloy-export.json

Round-trip example — export from one instance and import into another:

curl -s "$SOURCE_URL/api/v1/export?org_id=$ORG_ID" \
  -H "Authorization: Bearer $SOURCE_TOKEN" \
  | curl -s -X POST "$TARGET_URL/api/v1/import" \
    -H "Authorization: Bearer $TARGET_TOKEN" \
    -H "Content-Type: application/json" \
    -d @-

Validation errors — returns 422 if the export version is unsupported:

curl -s -X POST "$BASE_URL/api/v1/import" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":99,"source":"test","exported_at":"2026-01-01T00:00:00Z","projects":[],"labels":[],"workflows":[],"users":[]}'

# → 422 {"error":"Validation error","details":["unsupported export version: 99. Expected: 1"]}

Webhooks

Webhooks deliver real-time event notifications to external URLs via HTTP POST. Events are signed with HMAC-SHA256 using the webhook secret.

Create Webhook

POST /api/v1/orgs/{org_id}/webhooks — requires auth

Supported event types: ticket.created, ticket.updated, ticket.status_changed, comment.created, sprint.started, sprint.completed

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/alloy",
    "event_types": ["ticket.created", "ticket.updated"]
  }' | jq .

{
  "id": "cc0e8400-...",
  "org_id": "660e8400-...",
  "url": "...",
  "secret": "...",
  "event_types": [
    "...",
    "..."
  ],
  "active": true,
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Note: The secret field is only returned on creation. Store it securely — it is used to verify webhook signatures via the X-Alloy-Signature header.

List Webhooks

GET /api/v1/orgs/{org_id}/webhooks — requires auth

curl -s "$BASE_URL/api/v1/orgs/$ORG_ID/webhooks" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a paginated list of WebhookResponse objects (without the secret field).

Get Webhook

GET /api/v1/webhooks/{id} — requires auth

curl -s "$BASE_URL/api/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .

{
  "id": "cc0e8400-...",
  "org_id": "660e8400-...",
  "url": "https://example.com/hooks/alloy",
  "event_types": ["ticket.created", "ticket.updated"],
  "active": true,
  "created_at": "2026-03-28-...",
  "updated_at": "2026-03-28-..."
}

Delete Webhook

DELETE /api/v1/webhooks/{id} — requires auth

curl -s -X DELETE "$BASE_URL/api/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns 204 No Content on success.

List Webhook Deliveries

GET /api/v1/webhooks/{webhook_id}/deliveries — requires auth

curl -s "$BASE_URL/api/v1/webhooks/$WEBHOOK_ID/deliveries" \
  -H "Authorization: Bearer $TOKEN" | jq .

SSO Authentication

Single sign-on via OpenID Connect (OIDC) with PKCE. Requires the org to have an SSO provider configured.

SSO Discovery

GET /api/v1/auth/sso/discover — no auth required

Returns the IdP authorization URL and state parameter to begin the SSO flow.

curl -s "$BASE_URL/api/v1/auth/sso/discover?org_id=$ORG_ID" | jq .

Redirect the user’s browser to authorization_url to begin login.

SSO Callback

GET /api/v1/auth/sso/callback — no auth required

curl -s "$BASE_URL/api/v1/auth/sso/callback?code=$AUTH_CODE&state=$STATE" | jq .

SCIM Provisioning

SCIM 2.0 endpoints for automated user and group provisioning from identity providers. All SCIM endpoints require a Bearer token and are mounted at /scim/v2/.

Configuration: SCIM provisioning requires an SSO provider to be configured for the org. The SCIM bearer token is generated during SSO setup.

Service Provider Config

GET /scim/v2/ServiceProviderConfig — requires SCIM bearer token

curl -s "$BASE_URL/scim/v2/ServiceProviderConfig" \
  -H "Authorization: Bearer $SCIM_TOKEN" | jq .

Returns the SCIM service provider configuration describing supported features.

List Users (SCIM)

GET /scim/v2/Users — requires SCIM bearer token

curl -s "$BASE_URL/scim/v2/Users" \
  -H "Authorization: Bearer $SCIM_TOKEN" | jq .

Create User (SCIM)

POST /scim/v2/Users — requires SCIM bearer token

curl -s "$BASE_URL/scim/v2/Users" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userName": "new@example.com", "displayName": "New User"}' | jq .

Returns the created ScimUser with 201 Created.

Get User (SCIM)

GET /scim/v2/Users/{id} — requires SCIM bearer token

curl -s "$BASE_URL/scim/v2/Users/$USER_ID" \
  -H "Authorization: Bearer $SCIM_TOKEN" | jq .

Returns a ScimUser object.

Update User (SCIM)

PATCH /scim/v2/Users/{id} — requires SCIM bearer token

Uses SCIM PATCH operations. Common operation: deactivate a user.

curl -s -X PATCH "$BASE_URL/scim/v2/Users/$USER_ID" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Operations": [{"op": "replace", "path": "active", "value": false}]
  }' | jq .

Returns the updated ScimUser.

List Groups (SCIM)

GET /scim/v2/Groups — requires SCIM bearer token

curl -s "$BASE_URL/scim/v2/Groups" \
  -H "Authorization: Bearer $SCIM_TOKEN" | jq .

Create Group (SCIM)

POST /scim/v2/Groups — requires SCIM bearer token

curl -s "$BASE_URL/scim/v2/Groups" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Design", "members": [{"value": "'$USER_ID'"}]}' | jq .

Returns the created ScimGroup with 201 Created.

Get Group (SCIM)

GET /scim/v2/Groups/{id} — requires SCIM bearer token

curl -s "$BASE_URL/scim/v2/Groups/$GROUP_ID" \
  -H "Authorization: Bearer $SCIM_TOKEN" | jq .

Returns a ScimGroup object.

Update Group (SCIM)

PATCH /scim/v2/Groups/{id} — requires SCIM bearer token

curl -s -X PATCH "$BASE_URL/scim/v2/Groups/$GROUP_ID" \
  -H "Authorization: Bearer $SCIM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Operations": [{"op": "replace", "path": "displayName", "value": "Platform Engineering"}]
  }' | jq .

Returns the updated ScimGroup.

GitHub Integration

Receives GitHub webhook events to automatically transition ticket statuses based on pull request activity.

Configuration: Requires ALLOY_GITHUB_WEBHOOK_SECRET environment variable. Configure a GitHub webhook pointing to this endpoint with the pull_request event.

Receive GitHub Webhook

POST /api/v1/integrations/github/webhook — no auth required (signature verified)

The handler parses ticket references (e.g., PROJ-123) from PR titles and branch names, then transitions tickets:

• PR opened/reopened → In Review
• PR closed + merged → Done
• PR closed (not merged) → In Progress

{
  "status": "processed",
  "ticket_refs_found": ["ALLOY-42", "ALLOY-43"],
  "transitions": [
    {"ticket_ref": "ALLOY-42", "old_status": "In Progress", "new_status": "In Review"},
    {"ticket_ref": "ALLOY-43", "old_status": "In Progress", "new_status": "In Review"}
  ]
}

Slack Integration

Slack integration provides slash commands for ticket management and real-time notifications.

Configuration: Requires ALLOY_SLACK_SIGNING_SECRET, ALLOY_SLACK_BOT_TOKEN, and optionally ALLOY_SLACK_DEFAULT_CHANNEL environment variables.

Receive Slack Command

POST /api/v1/integrations/slack/commands — no auth required (signature verified)

Request body is application/x-www-form-urlencoded with Slack command fields.

Supported commands:

• /ticket create PROJ Title here — creates a new ticket
• /ticket PROJ-42 — looks up a ticket by reference

{
  "response_type": "in_channel",
  "blocks": [
    {
      "type": "section",
      "text": {"type": "mrkdwn", "text": "*ALLOY-42: Fix login bug*"},
      "fields": [
        {"type": "mrkdwn", "text": "*Status:* In Progress"},
        {"type": "mrkdwn", "text": "*Priority:* High"}
      ]
    }
  ]
}

Dispatch Slack Notification

POST /api/v1/integrations/slack/notify — requires auth

curl -s "$BASE_URL/api/v1/integrations/slack/notify" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"notification_type\": \"status_change\",
    \"ticket_id\": \"$TICKET_ID\",
    \"channel_id\": \"C0123456789\",
    \"old_status\": \"In Progress\",
    \"new_status\": \"Done\",
    \"actor_name\": \"Jane Smith\"
  }" | jq .

{
  "status": "queued",
  "notification_type": "status_change"
}

Receive Slack Event

POST /api/v1/integrations/slack/events — no auth required (signature verified)

Handles Slack Events API payloads, including URL verification challenges and message events for comment syncing.

# URL verification (Slack sends this during setup)
curl -s "$BASE_URL/api/v1/integrations/slack/events" \
  -H "Content-Type: application/json" \
  -d '{"type": "url_verification", "challenge": "abc123"}' | jq .

{
  "challenge": "abc123",
  "status": "ok"
}

Create Thread Mapping

POST /api/v1/integrations/slack/thread-mappings — requires auth

Links a Slack thread to an Alloy ticket for bi-directional comment syncing.

curl -s "$BASE_URL/api/v1/integrations/slack/thread-mappings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"ticket_id\": \"$TICKET_ID\",
    \"channel_id\": \"C0123456789\",
    \"thread_ts\": \"1679012345.678900\"
  }" | jq .

{
  "id": "ee0e8400-...",
  "ticket_id": "aa0e8400-...",
  "channel_id": "C0123456789",
  "thread_ts": "1679012345.678900",
  "created_at": "2026-03-28-..."
}

Attachments

Request Upload URL

Get a presigned S3 URL for uploading a file.

POST /api/v1/tickets/{ticket_id}/attachments/presign — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/attachments/presign" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename": "screenshot.png", "content_type": "image/png", "size_bytes": 102400}' | jq .

{
  "upload_url": "https://s3.amazonaws.com/...",
  "s3_key": "..."
}

Confirm Upload

After uploading the file to the presigned URL, confirm the attachment.

POST /api/v1/tickets/{ticket_id}/attachments/confirm — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/attachments/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"filename\": \"screenshot.png\",
    \"content_type\": \"image/png\",
    \"size_bytes\": 102400,
    \"s3_key\": \"attachments/abc123/screenshot.png\",
    \"uploaded_by\": \"$USER_ID\"
  }" | jq .

{
  "id": "110e8400-...",
  "ticket_id": "aa0e8400-...",
  "filename": "screenshot.png",
  "content_type": "image/png",
  "size_bytes": 102400,
  "s3_key": "attachments/abc123/screenshot.png",
  "uploaded_by": "550e8400-...",
  "created_at": "2026-03-28-...",
  "download_url": null
}

List Attachments

GET /api/v1/tickets/{ticket_id}/attachments — requires auth

curl -s "$BASE_URL/api/v1/tickets/$TICKET_ID/attachments" \
  -H "Authorization: Bearer $TOKEN" | jq .

Returns a paginated list of AttachmentResponse objects.

Health

Health Check

GET /health — no auth required

curl -s "$BASE_URL/health" | jq .

{
  "status": "ok",
  "service": "alloy",
  "version": "0.1.0",
  "database": "sqlite",
  "db_healthy": true,
  "migration_version": "...",
  "uptime_seconds": "..."
}

Version

Version Info

GET /api/v1/version — no auth required

curl -s "$BASE_URL/api/v1/version" | jq .

{
  "version": "0.1.0",
  "service": "alloy",
  "profile": "..."
}

Deployment and Operations Guide

This guide covers deploying and operating Alloy — from single-developer SQLite to team PostgreSQL with integrations.

SQLite vs PostgreSQL: Which Backend?

Start with SQLite if you’re evaluating Alloy or running it for personal use. Use PostgreSQL when you need multi-tenant isolation, team access, or production reliability.

Migrating from SQLite to PostgreSQL

There is no built-in migration tool. The recommended approach:

1. Stand up a PostgreSQL instance and start Alloy pointed at it (migrations run automatically)
2. Export your data from the SQLite instance using the API (list projects, tickets, etc.)
3. Import into PostgreSQL via the API
4. Switch your ALLOY_DATABASE_URL to the PostgreSQL connection string

SQLite Deployment

The simplest deployment — a single binary with a single database file.

# Start with defaults (creates ./alloy.db automatically)
cargo run -p alloy-cli -- serve

# Or with a prebuilt binary
alloy serve

Data location: By default, alloy.db is created in the current working directory. Override with:

ALLOY_DATABASE_URL=sqlite:///var/data/alloy.db alloy serve

Backup: Just copy the .db file while the server is stopped (or use SQLite’s .backup command for online backup):

cp alloy.db alloy.db.backup

PostgreSQL Deployment

Using Docker Compose (recommended for development)

The repository includes a docker-compose.yml that runs PostgreSQL 16 and MinIO (S3-compatible storage for attachments):

docker compose up -d

This starts:

• PostgreSQL on port 5432 (user: postgres, password: postgres, database: alloy_dev)
• MinIO on port 9000 (console on 9001, user: minioadmin, password: minioadmin)
• minio-init creates the alloy-attachments bucket automatically

Then start Alloy pointed at PostgreSQL:

ALLOY_DATABASE_URL=postgres://postgres:postgres@localhost:5432/alloy_dev alloy serve

Connection string format

postgres://USER:PASSWORD@HOST:PORT/DATABASE

Multi-tenancy and RLS

PostgreSQL mode enables Row-Level Security (RLS) for full multi-tenant isolation:

• Each request sets app.tenant_id via SET LOCAL in the transaction
• RLS policies ensure tenants can only see their own data
• This is transparent to the application — queries return only tenant-scoped rows
• No data leaks between organizations, even if a bug skips application-level filtering

TLS / HTTPS

Alloy supports automatic TLS certificate provisioning via Let’s Encrypt using the ACME protocol. When TLS is enabled, the server listens over HTTPS with no reverse proxy required.

Enabling automatic TLS

Pass --tls-domain to alloy serve with the public domain name:

alloy serve --tls-domain api.example.com --tls-contact admin@example.com

This will:

1. Automatically request a TLS certificate from Let’s Encrypt for api.example.com
2. Cache the certificate on disk (default: ./acme_cache)
3. Serve HTTPS on the configured port (default 3000)

CLI flags

Environment variables (TLS)

Example: production HTTPS

alloy serve \
  --tls-domain api.example.com \
  --tls-contact ops@example.com \
  --port 443

Once running, verify with curl:

curl -s https://api.example.com/health

Expected response:

{"status":"ok"}

Example: staging / testing

Use --tls-staging to test certificate provisioning without hitting production rate limits:

alloy serve \
  --tls-domain staging.example.com \
  --tls-contact ops@example.com \
  --tls-staging

Docker with TLS

Mount a volume for certificate persistence across container restarts:

docker run -d \
  --name alloy \
  -p 443:443 \
  -v alloy-data:/data \
  -v alloy-certs:/certs \
  -e ALLOY_DATABASE_URL=sqlite:///data/alloy.db \
  alloy \
  serve --tls-domain api.example.com --tls-contact ops@example.com --tls-cache-dir /certs --port 443

Notes

• DNS must resolve first: The domain must point to your server before ACME validation can succeed.
• Port 443: Let’s Encrypt HTTP-01 challenge may require port 80 or 443 to be reachable. If running behind a firewall, ensure the challenge port is open.
• Certificate renewal: Certificates are renewed automatically before expiration. Keep the cache directory persistent.
• Without TLS flags: The server runs plain HTTP exactly as before — no TLS overhead.

Docker Deployment

Building the image

docker build -t alloy .

The multi-stage Dockerfile produces a minimal Debian-based image with just the alloy binary.

Running with SQLite

docker run -d \
  --name alloy \
  -p 3000:3000 \
  -v alloy-data:/data \
  alloy

Data is stored at /data/alloy.db inside the container. The volume mount persists it across container restarts.

Running with PostgreSQL

docker run -d \
  --name alloy \
  -p 3000:3000 \
  -e ALLOY_DATABASE_URL=postgres://user:pass@db-host:5432/alloy \
  -e ALLOY_JWT_PRIVATE_KEY_FILE=/secrets/private.pem \
  -e ALLOY_JWT_PUBLIC_KEY_FILE=/secrets/public.pem \
  -v /path/to/secrets:/secrets:ro \
  alloy

Volume mounts

Environment Variables Reference

Core

Authentication (JWT)

S3 / Object Storage (Attachments)

Security

Rate Limiting

Slack Integration

GitHub Integration

SCIM Provisioning

MCP Server

TUI

Auto-Migration Behavior

On startup, Alloy checks ALLOY_AUTO_MIGRATE (defaults to true):

• If true: Runs all pending migrations from the embedded migration set. Migrations are compiled into the binary — no external SQL files needed at runtime.
• If false: Skips migrations entirely. Use this in environments where you run migrations as a separate step.

Migrations are idempotent — re-running an already-applied migration is a no-op. The migration runner detects the database backend (SQLite or PostgreSQL) and applies the correct dialect automatically.

MCP Server

The MCP server (alloy-mcp) lets AI assistants like Claude interact with Alloy. For complete setup instructions, configuration examples, and troubleshooting, see the dedicated MCP Guide.

For a full reference of available tools, parameters, and response formats, see the MCP Tools Reference.

Integrations Setup

Slack

1. Create a Slack App at api.slack.com/apps
2. Enable Event Subscriptions and set the request URL to https://your-alloy-host/api/v1/integrations/slack/events
3. Enable Slash Commands (e.g., /alloy) with the request URL https://your-alloy-host/api/v1/integrations/slack/commands
4. Under OAuth & Permissions, add bot scopes: chat:write, commands
5. Install the app to your workspace and copy the Bot User OAuth Token
6. Set environment variables:

   ALLOY_SLACK_SIGNING_SECRET=your_signing_secret
   ALLOY_SLACK_BOT_TOKEN=xoxb-your-bot-token
   ALLOY_SLACK_NOTIFICATION_CHANNEL=engineering  # optional
   

GitHub

1. Create a GitHub App or use repository webhooks
2. Set the webhook URL to https://your-alloy-host/api/v1/integrations/github/webhook
3. Select events: push, pull_request, issues, etc.
4. Generate a webhook secret and set:

   ALLOY_GITHUB_WEBHOOK_SECRET=your_webhook_secret
   

Okta SSO (OIDC)

SSO is configured per-organization via the API (not environment variables). To set up OIDC:

1. In Okta, create a new Web Application with:
   • Sign-in redirect URI: https://your-alloy-host/api/v1/auth/sso/callback
   • Sign-out redirect URI: https://your-alloy-host
2. Note the Client ID, Client Secret, and Issuer URL (e.g., https://your-org.okta.com/oauth2/default)
3. Register the identity provider via the Alloy API for your organization:

   curl -X POST https://your-alloy-host/api/v1/orgs/{org_id}/identity-providers \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "provider_type": "oidc",
       "provider_name": "okta",
       "issuer_url": "https://your-org.okta.com/oauth2/default",
       "client_id": "your-client-id",
       "client_secret": "your-client-secret"
     }'
   

4. Users can then sign in via GET /api/v1/auth/sso/login?org={org_slug}

Troubleshooting

Port conflicts

Symptom: error binding to 0.0.0.0:3000: Address already in use

Solution: Either stop the other process using port 3000, or set a different port:

PORT=3001 alloy serve

Migration failures

Symptom: migration error or refinery errors on startup

Solutions:

• Ensure the database is accessible (correct ALLOY_DATABASE_URL)
• For PostgreSQL, verify the user has CREATE TABLE / ALTER TABLE permissions
• If a migration was partially applied, check the refinery_schema_history table and fix manually
• Set ALLOY_AUTO_MIGRATE=false to skip auto-migration and run migrations separately

Authentication errors

Symptom: 401 Unauthorized on API requests

Solutions:

• Verify JWT keys are set: both ALLOY_JWT_PRIVATE_KEY (or _FILE) and ALLOY_JWT_PUBLIC_KEY (or _FILE) are required
• For API key auth, ensure the key starts with alloy_live_ or alloy_test_
• Check ALLOY_JWT_ISSUER and ALLOY_JWT_AUDIENCE match between token issuer and verifier
• If using SSO, confirm the identity provider’s issuer_url is correct and reachable

Database connection issues (PostgreSQL)

Symptom: error connecting to database or connection timeouts

Solutions:

• Verify PostgreSQL is running: pg_isready -h localhost -p 5432
• Check the connection string format: postgres://user:password@host:port/database
• Ensure the database exists: createdb alloy_dev
• For Docker Compose: docker compose up -d postgres and wait for the health check

CORS errors

Symptom: Browser console shows CORS errors when calling the API

Solution: Set allowed origins:

ALLOY_CORS_ORIGINS=http://localhost:5173,https://your-app.com alloy serve

Slack integration not working

Symptom: Slash commands or events not reaching Alloy

Solutions:

• Verify ALLOY_SLACK_SIGNING_SECRET matches your Slack app’s signing secret
• Ensure webhook URLs are publicly reachable (use ngrok for local development)
• Check that bot scopes include chat:write and commands

MCP server connection issues

Symptom: Claude Desktop can’t connect to the MCP server

Solution: See the troubleshooting section in the MCP Guide for detailed solutions covering connection errors, authentication issues, and configuration problems.

MCP Guide

Alloy includes a built-in Model Context Protocol (MCP) server that lets AI assistants interact with your projects, tickets, sprints, and time tracking directly.

Overview

The alloy-mcp server exposes Alloy’s project management capabilities as MCP tools and resources. AI assistants like Claude can create tickets, search backlogs, log time, query sprint burndown, and more — all through the standard MCP protocol.

Transport modes:

Key features:

• 67 tools covering tickets, comments, labels, tags, projects, sprints, teams, workflows, time tracking, finance, and organization management
• 15 slash commands (MCP prompts) for guided workflows — see the MCP Tools Reference for the full list
• Resource URIs for browsing projects, tickets, sprints, and user assignments
• Authenticated via Alloy API keys — the MCP server proxies requests to the Alloy API
• Protocol version: 2024-11-05

Quick Start: From Build to Working in 6 Steps

Follow these numbered steps to go from a fresh checkout to a working MCP integration.

Step 1: Build the binary

Build the alloy-mcp binary from the workspace root:

cargo build --release -p alloy-mcp

The binary is placed at target/release/alloy-mcp. Optionally, copy it somewhere on your $PATH:

cp target/release/alloy-mcp ~/.local/bin/

Step 2: Start the Alloy API server

The MCP server needs a running Alloy API to proxy requests to. Start it in a separate terminal:

cargo run --release -p alloy-api -- serve

Or if you have the binary installed:

alloy serve

See Getting Started or Deployment for full details.

Step 3: Create an API key

Via the CLI:

alloy auth api-key create --name "MCP Server"

This prints the full key (starting with alloy_live_ or alloy_test_). Copy it immediately — the full key is only shown once.

Via curl:

curl -s "$BASE_URL/api/v1/api-keys" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "MCP Server", "scopes": ["read", "write"]}' | jq .

Expected response:

{
  "id": "770e8400-...",
  "name": "MCP Server",
  "key": "alloy_live_abc123...",
  "key_prefix": "alloy_live_...",
  "scopes": ["read", "write"],
  "project_ids": [],
  "created_at": "2026-03-28-...",
  "expires_at": null
}

Save the key field — you will need it for ALLOY_API_TOKEN below.

Step 4: Test the MCP server manually

Before configuring any AI assistant, verify the binary works end-to-end on its own.

Test the stdio transport directly:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | \
  ALLOY_API_URL=http://localhost:3000 \
  ALLOY_API_TOKEN=alloy_live_your_key \
  alloy-mcp

You should receive a JSON-RPC response containing serverInfo with name: "alloy-mcp". If you see an error instead, fix the issue before proceeding — the AI assistant configuration will not work until this step succeeds.

Test API connectivity:

curl -s http://localhost:3000/api/v1/auth/me \
  -H "Authorization: Bearer $ALLOY_API_TOKEN" | jq .

You should see your user details (user_id, org_id, email, role).

Step 5: Configure your AI assistant

Choose the assistant you want to use with Alloy.

Claude Code (project-level)

Add the MCP server to your project’s .claude/mcp.json:

{
  "mcpServers": {
    "alloy": {
      "command": "alloy-mcp",
      "env": {
        "ALLOY_API_URL": "http://localhost:3000",
        "ALLOY_API_TOKEN": "alloy_live_your_api_key_here"
      }
    }
  }
}

This makes Alloy available only when working inside that project directory.

Claude Code (global)

To make Alloy available across all projects, add the same configuration to ~/.claude/mcp.json instead:

{
  "mcpServers": {
    "alloy": {
      "command": "alloy-mcp",
      "env": {
        "ALLOY_API_URL": "http://localhost:3000",
        "ALLOY_API_TOKEN": "alloy_live_your_api_key_here"
      }
    }
  }
}

Tip: If alloy-mcp is not on your $PATH, use the full path in the command field (e.g., /Users/you/repos/alloy/target/release/alloy-mcp).

Claude Desktop

Add the following to your Claude Desktop MCP configuration. On macOS this is ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "alloy": {
      "command": "alloy-mcp",
      "env": {
        "ALLOY_API_URL": "http://localhost:3000",
        "ALLOY_API_TOKEN": "alloy_live_your_api_key_here"
      }
    }
  }
}

Step 6: Restart and verify

Restart your assistant — Claude Code and Claude Desktop do not pick up MCP config changes automatically. You must restart them after editing the configuration.

• Claude Code: Close and reopen the Claude Code session (or restart the terminal)
• Claude Desktop: Quit and relaunch the application

Verify tools appear: Open Claude and check that Alloy tools are listed (e.g., create_ticket, search_tickets, ping). Try a simple command:

“Use the ping tool to check the Alloy connection”

If the tool executes and returns a response, your MCP setup is working correctly.

HTTP Transport

For remote or shared environments, run the MCP server in HTTP mode instead of stdio:

ALLOY_API_URL=http://localhost:3000 \
ALLOY_API_TOKEN=alloy_live_your_api_key_here \
alloy-mcp --http 0.0.0.0:3001

The HTTP transport:

• Listens on the specified bind address (default port 3001 in the example above)
• Authenticates each request via a Bearer token in the Authorization header
• Exposes OAuth 2.1 discovery metadata at GET /.well-known/oauth-authorization-server

Connecting an MCP client to the HTTP server:

Point your MCP client at http://<host>:3001 and provide the API token as a Bearer token. Consult your client’s documentation for HTTP/SSE transport configuration.

Troubleshooting

Connection errors

Authentication errors

Tools not appearing

Debugging MCP communication

To see raw JSON-RPC messages, run the MCP server manually and inspect its output:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  ALLOY_API_URL=http://localhost:3000 \
  ALLOY_API_TOKEN=alloy_live_your_key \
  alloy-mcp 2>mcp-stderr.log

Check mcp-stderr.log for diagnostic messages. If the server starts but returns errors for tool calls, the issue is likely with the API server or API key — re-run Step 4 to isolate the problem.

MCP Tools Reference

Complete reference for all tools, resources, and slash commands (prompts) exposed by the Alloy MCP server. For setup instructions, see the MCP Guide.

Table of Contents

• Tools vs Slash Commands
• Tools Overview
• Connectivity — ping, whoami
• Tickets — create_ticket, get_ticket, search_tickets, update_ticket, transition_ticket, batch_transition, batch_update_tickets, assign_ticket, get_my_tickets, delete_ticket
• Comments — add_comment, list_comments, update_comment, delete_comment
• Label Management — create_label, list_labels, add_ticket_label, remove_ticket_label, get_label, update_label, delete_label
• Tag Management — set_tags, get_tags, delete_tag, search_by_tag
• Project Management — create_project, list_projects, get_project, update_project, delete_project
• Sprint Lifecycle — create_sprint, list_sprints, update_sprint, start_sprint, complete_sprint, get_sprint_burndown, get_sprint, delete_sprint
• Team Management — create_team, list_teams, delete_team
• Workflow Management — create_workflow, list_workflows, update_workflow, get_workflow, delete_workflow
• Projects & Sprints — get_project_summary
• Organization & Access — list_members, create_invite, list_invites, add_project_member, remove_project_member, list_project_members, create_api_key, list_api_keys, delete_api_key
• Activity — get_ticket_activity
• Time Tracking — log_time, get_time_entry, update_time_entry, delete_time_entry, list_time_entries
• Finance & Reporting — get_time_report, get_capitalization_report, submit_time_entry, approve_time_entry, get_capitalization_export
• Data Export & Import — export_data, import_data
• Resources
• Enums Reference
• Pagination
• Slash Commands (Prompts)
• Error Handling

Tools vs Slash Commands

The Alloy MCP server exposes two types of capabilities:

• Tools are functions the AI assistant calls on your behalf (e.g., create_ticket, search_tickets). You don’t invoke them directly — the assistant decides when to use them based on your request.
• Slash commands (MCP prompts) are pre-built workflows you invoke explicitly by typing a command like /alloy:standup. They provide the assistant with structured instructions to accomplish a multi-step task using one or more tools. Think of them as recipes that orchestrate several tool calls into a coherent workflow.

Tools Overview

The Alloy MCP server exposes 69 tools organized into fourteen categories: