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.
+ +Authentication Header
+X-API-Key: ck_your_api_key_here
+ 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 | +
+ 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"
+}
+ 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.
+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 }}"
+ }'
+