Complete API reference for managing projects — checking linked repositories, linking repos with auto-webhook configuration, listing and creating projects with org scoping, and deleting projects.

Project API

Manage project links between CodeSpar agents and GitHub repositories. When a repository is linked, CodeSpar automatically configures webhooks (if WEBHOOK_BASE_URL is set) to receive push, pull request, and workflow events.

Endpoints Overview

Method	Path	Description
`GET`	`/api/project?agentId=<id>`	Check if an agent has a linked project
`POST`	`/api/project/link`	Link a repository to an agent
`GET`	`/api/projects`	List all projects (scoped by org)
`POST`	`/api/projects`	Create a new project with agent
`DELETE`	`/api/projects/:id`	Delete a project and its agent

Check Linked Project

Check which repository is linked to a specific agent.

GET /api/project?agentId=<agent-id>

Query Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	The agent identifier to check

Request

curl "http://localhost:3000/api/project?agentId=agent-proj-abc123"

Response (linked)

{
  "linked": true,
  "config": {
    "id": "proj-001",
    "name": "codespar",
    "repo": "codespar/codespar",
    "repoUrl": "https://github.com/codespar/codespar",
    "defaultBranch": "main",
    "webhookConfigured": true,
    "linkedAt": "2024-01-15T13:30:00Z",
    "linkedBy": "slack:U1234ABCD"
  }
}

Response (not linked)

{
  "linked": false
}

`ProjectConfig` Type

interface ProjectConfig {
  id: string;              // Unique project identifier (e.g., "proj-001")
  name: string;            // Display name, derived from repo name
  repo: string;            // GitHub repo in "owner/name" format
  repoUrl: string;         // Full GitHub URL
  defaultBranch: string;   // Default branch (e.g., "main", "master")
  webhookConfigured: boolean; // Whether GitHub webhook was auto-configured
  webhookId?: number;      // GitHub webhook ID (if auto-configured)
  linkedAt: string;        // ISO 8601 timestamp of when the link was created
  linkedBy: string;        // Identity of who linked (e.g., "slack:U1234ABCD")
}

Link a Repository

Link a GitHub repository to an agent. If WEBHOOK_BASE_URL is set and GITHUB_TOKEN has admin permissions, a webhook is automatically created on the repository.

POST /api/project/link

Request Body

Field	Type	Required	Description
`agentId`	string	Yes	Agent to link the repo to
`repo`	string	Yes	GitHub repo in `owner/name` format, or a full GitHub URL

Request

curl -X POST http://localhost:3000/api/project/link \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-proj-abc123",
    "repo": "codespar/codespar"
  }'

Using a full URL:

curl -X POST http://localhost:3000/api/project/link \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-proj-abc123",
    "repo": "https://github.com/codespar/codespar"
  }'

Response

{
  "success": true,
  "config": {
    "id": "proj-001",
    "name": "codespar",
    "repo": "codespar/codespar",
    "repoUrl": "https://github.com/codespar/codespar",
    "defaultBranch": "main",
    "webhookConfigured": true,
    "webhookId": 123456789,
    "linkedAt": "2024-01-15T13:30:00Z",
    "linkedBy": "api"
  }
}

What Happens During Linking

CodeSpar validates the repository exists and GITHUB_TOKEN has access
The repo's default branch is detected
A project configuration record is created
If WEBHOOK_BASE_URL is set and the token has admin:repo_hook scope, a GitHub webhook is auto-configured to send push, pull_request, workflow_run, and check_run events to {WEBHOOK_BASE_URL}/webhooks/github
The agent is associated with the project

Error Responses

Repository not found or no access (404):

curl -X POST http://localhost:3000/api/project/link \
  -H "Content-Type: application/json" \
  -d '{"agentId": "agent-001", "repo": "nonexistent/repo"}'

{
  "error": "Repository not found or insufficient permissions",
  "code": "REPO_NOT_FOUND",
  "status": 404
}

Already linked (409):

{
  "error": "Agent already has a linked project. Unlink first.",
  "code": "ALREADY_LINKED",
  "status": 409
}

Missing GitHub token (400):

{
  "error": "GITHUB_TOKEN is not configured",
  "code": "MISSING_CONFIG",
  "status": 400
}

List All Projects

Retrieve all projects. When the x-org-id header is provided, results are scoped to that organization.

GET /api/projects

Headers

Header	Required	Description
`x-org-id`	No	Organization ID to scope results. Without this header, all projects across all orgs are returned.

Request

# All projects
curl http://localhost:3000/api/projects

# Projects scoped to an organization
curl http://localhost:3000/api/projects \
  -H "x-org-id: org-acme-corp"

Response

{
  "projects": [
    {
      "id": "proj-001",
      "name": "codespar",
      "repo": "codespar/codespar",
      "repoUrl": "https://github.com/codespar/codespar",
      "defaultBranch": "main",
      "webhookConfigured": true,
      "agentId": "agent-proj-abc123",
      "agentStatus": "ACTIVE",
      "orgId": "org-acme-corp",
      "createdAt": "2024-01-15T13:30:00Z"
    },
    {
      "id": "proj-002",
      "name": "frontend",
      "repo": "acme/frontend",
      "repoUrl": "https://github.com/acme/frontend",
      "defaultBranch": "main",
      "webhookConfigured": true,
      "agentId": "agent-proj-def456",
      "agentStatus": "IDLE",
      "orgId": "org-acme-corp",
      "createdAt": "2024-01-16T09:00:00Z"
    }
  ]
}

`ProjectListEntry` Type

interface ProjectListEntry {
  id: string;                 // Unique project identifier
  name: string;               // Display name
  repo: string;               // GitHub repo "owner/name"
  repoUrl: string;            // Full GitHub URL
  defaultBranch: string;      // Default branch name
  webhookConfigured: boolean; // Whether webhook is set up
  agentId: string;            // Associated agent ID
  agentStatus: string;        // Agent state: "ACTIVE", "IDLE", "ERROR"
  orgId?: string;             // Organization ID (if multi-tenant)
  createdAt: string;          // ISO 8601 creation timestamp
}

Create Project

Create a new project with an associated agent. If WEBHOOK_BASE_URL and GITHUB_TOKEN are configured, the webhook is automatically set up.

POST /api/projects

Headers

Header	Required	Description
`x-org-id`	No	Organization to create the project in

Request Body

Field	Type	Required	Description
`repo`	string	Yes	GitHub repo in `owner/name` format
`name`	string	No	Display name for the project. If omitted, derived from the repo name.

Request

curl -X POST http://localhost:3000/api/projects \
  -H "Content-Type: application/json" \
  -H "x-org-id: org-acme-corp" \
  -d '{
    "repo": "acme/api-service",
    "name": "API Service"
  }'

Minimal request (name auto-derived from repo):

curl -X POST http://localhost:3000/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "acme/api-service"
  }'

Response

{
  "id": "proj-003",
  "agentId": "agent-proj-ghi789",
  "repo": "acme/api-service",
  "orgId": "org-acme-corp",
  "webhookUrl": "https://codespar.example.com/webhooks/github",
  "webhookConfigured": true
}

What Happens During Creation

CodeSpar validates the repository exists and is accessible
A new Project Agent is spawned for the project
A project record is created (scoped to the org if x-org-id is provided)
If WEBHOOK_BASE_URL is set, a webhook is auto-configured on the GitHub repository
The agent starts monitoring the repository based on its autonomy level

Delete Project

Remove a project, its associated agent, and the GitHub webhook (if one was configured).

DELETE /api/projects/:id

Path Parameters

Parameter	Type	Description
`id`	string	Project ID to delete

Headers

Header	Required	Description
`x-org-id`	No	Organization scope (ensures you can only delete projects in your org)

Request

curl -X DELETE http://localhost:3000/api/projects/proj-003

With organization scoping:

curl -X DELETE http://localhost:3000/api/projects/proj-003 \
  -H "x-org-id: org-acme-corp"

Response

{
  "success": true,
  "removed": {
    "id": "proj-003",
    "agentTerminated": true,
    "webhookRemoved": true
  }
}

What Happens During Deletion

The associated Project Agent is terminated (and any ephemeral agents it spawned)
The GitHub webhook is removed from the repository (if it was auto-configured)
The project record is deleted from storage
An audit log entry is created for the deletion

Error Response

{
  "error": "Project not found",
  "code": "PROJECT_NOT_FOUND",
  "status": 404
}

Next Steps

Agent API — Manage agent lifecycle
Webhook API — GitHub webhook processing
Channel API — Manage messaging channels
Link a Repository Guide — Step-by-step guide

Project API

On this page