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, Cursor, or Codex) 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`, `cursor`, or `codex` (default: `claude`)
`stream` | boolean | Optional | Enable streaming (default: `true`)
`model` | string | Optional | Model identifier for the AI provider (loading from constants...)
`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"
      }
    }