Claude Code UI

API Documentation
Back to App

Programmatically trigger AI agents to work on projects. Clone GitHub repositories or use existing project paths. Perfect for CI/CD pipelines, automated code reviews, and bulk processing.

Authentication

All API requests require authentication using an API key in the X-API-Key header.

Generate API keys in Settings → API & Tokens.

GitHub Credentials

For private repositories, store a GitHub token in settings or pass it with each request.

Note: GitHub tokens in the request override stored tokens.

Authentication Header

X-API-Key: ck_your_api_key_here

Agent

POST http://localhost:3001/api/agent

Trigger an AI agent (Claude or Cursor) to work on a project.

Request Body Parameters

Parameter Type Required Description
githubUrl string Conditional GitHub repository URL to clone. If path exists with same repo, reuses it. If path exists with different repo, returns error.
projectPath string Conditional Path to existing project OR destination for cloning. If omitted with githubUrl, auto-generates path. If used alone, must point to existing project directory.
message string Required Task for the AI agent
provider string Optional claude or cursor (default: claude)
stream boolean Optional Enable streaming (default: true)
model string Optional Model to use (for Cursor)
cleanup boolean Optional Auto-cleanup after completion (default: true). Only applies when cloning via githubUrl. Existing projects specified via projectPath are never cleaned up.
githubToken string Optional GitHub token for private repos
branchName string Optional Custom branch name to use. If provided, createBranch is automatically enabled. Branch names are validated against Git naming rules. Works with githubUrl or projectPath (if it has a GitHub remote).
createBranch boolean Optional Create a new branch after successful completion (default: false). Automatically set to true if branchName is provided. Works with githubUrl or projectPath (if it has a GitHub remote).
createPR boolean Optional Create a pull request after successful completion (default: false). PR title and description auto-generated from commit messages. Works with githubUrl or projectPath (if it has a GitHub remote).
Path Handling Behavior:

Scenario 1: Only githubUrl → Clones to auto-generated temporary path
Scenario 2: Only projectPath → Uses existing project at specified path
Scenario 3: Both provided → Clones githubUrl to projectPath

Validation: If projectPath exists and contains a git repository, the remote URL is compared with githubUrl. If URLs match, the existing repo is reused. If URLs differ, an error is returned.

Response (Streaming)

Server-sent events (SSE) format with real-time updates. Content-Type: text/event-stream

Response (Non-Streaming)

JSON object containing session details, assistant messages only (filtered), and token usage summary. Content-Type: application/json

Error Response

Returns error details with appropriate HTTP status code.

Basic Request

curl -X POST http://localhost:3001/api/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ck_..." \
  -d '{
    "githubUrl": "https://github.com/user/repo",
    "message": "Add error handling to main.js"
  }'
const response = await fetch('http://localhost:3001/api/agent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.CLAUDE_API_KEY
  },
  body: JSON.stringify({
    githubUrl: 'https://github.com/user/repo',
    message: 'Add error handling',
    stream: false
  })
});

const result = await response.json();
import requests
import os

response = requests.post(
    'http://localhost:3001/api/agent',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['CLAUDE_API_KEY']
    },
    json={
        'githubUrl': 'https://github.com/user/repo',
        'message': 'Add error handling',
        'stream': False
    }
)

print(response.json())

Streaming Response

data: {"type":"status","message":"Repository cloned"}
data: {"type":"thinking","content":"Analyzing..."}
data: {"type":"tool_use","tool":"read_file"}
data: {"type":"content","content":"Done!"}
data: {"type":"done"}

Non-Streaming Response

{
  "success": true,
  "sessionId": "abc123",
  "messages": [
    {
      "type": "assistant",
      "message": {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "I've completed the task..."
          }
        ],
        "usage": {
          "input_tokens": 150,
          "output_tokens": 50
        }
      }
    }
  ],
  "tokens": {
    "inputTokens": 150,
    "outputTokens": 50,
    "cacheReadTokens": 0,
    "cacheCreationTokens": 0,
    "totalTokens": 200
  },
  "projectPath": "/path/to/project",
  "branch": {
    "name": "fix-authentication-bug-abc123",
    "url": "https://github.com/user/repo/tree/fix-authentication-bug-abc123"
  },
  "pullRequest": {
    "number": 42,
    "url": "https://github.com/user/repo/pull/42"
  }
}

Error Response

{
  "success": false,
  "error": "Directory exists with different repo"
}

Usage Patterns

Clone and Process Repository

Clone a repository to an auto-generated temporary path and process it.

Use Existing Project

Work with an existing project at a specific path.

Clone to Specific Path

Clone a repository to a custom location for later reuse.

CI/CD Integration

Integrate with GitHub Actions or other CI/CD pipelines.

Create Branch and Pull Request

Automatically create a new branch and pull request after the agent completes its work. Branch names are auto-generated from the message, and PR title/description are auto-generated from commit messages.

Use Existing Project

curl -X POST http://localhost:3001/api/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ck_..." \
  -d '{
    "projectPath": "/home/user/my-project",
    "message": "Refactor database queries"
  }'

Clone to Custom Path

curl -X POST http://localhost:3001/api/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ck_..." \
  -d '{
    "githubUrl": "https://github.com/user/repo",
    "projectPath": "/tmp/my-location",
    "message": "Review security",
    "cleanup": false
  }'

CI/CD (GitHub Actions)

- name: Trigger Agent
  run: |
    curl -X POST ${{ secrets.API_URL }}/api/agent \
      -H "X-API-Key: ${{ secrets.API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "githubUrl": "${{ github.repository }}",
        "message": "Review for security",
        "githubToken": "${{ secrets.GITHUB_TOKEN }}"
      }'

Create Branch and PR

curl -X POST http://localhost:3001/api/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ck_..." \
  -d '{
    "githubUrl": "https://github.com/user/repo",
    "message": "Fix authentication bug",
    "createBranch": true,
    "createPR": true,
    "stream": false
  }'

Custom Branch Name

curl -X POST http://localhost:3001/api/agent \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ck_..." \
  -d '{
    "githubUrl": "https://github.com/user/repo",
    "message": "Add user authentication",
    "branchName": "feature/user-auth",
    "createPR": true,
    "stream": false
  }'

Branch & PR Response

{
  "success": true,
  "branch": {
    "name": "feature/user-auth",
    "url": "https://github.com/user/repo/tree/feature/user-auth"
  },
  "pullRequest": {
    "number": 42,
    "url": "https://github.com/user/repo/pull/42"
  }
}