Organizations API¶

Manage monitored organizations through the API.

List Organizations¶

Get all organizations for the current account.

GET /api/organizations/

Response¶

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "my-org",
    "platform": "github",
    "external": false,
    "sync_status": "completed",
    "last_sync": "2026-02-28T10:30:00Z",
    "repo_count": 42,
    "health_score": 85
  }
]

Add Organization¶

Add a new organization to monitor.

POST /api/organizations/

Request Body¶

{
  "name": "my-org",
  "platform": "github",
  "external": false
}

Field	Type	Required	Description
`name`	string	Yes	Organization name/slug
`platform`	string	Yes	Platform: `github` or `gitlab`
`external`	boolean	No	Whether this is an external org (default: false)

Response¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-org",
  "platform": "github",
  "external": false,
  "sync_status": "pending",
  "last_sync": null,
  "repo_count": 0,
  "health_score": null
}

Status: 201 Created

Errors¶

Status	Description
`400`	Invalid platform or organization name
`409`	Organization already monitored

Get Organization¶

Get details for a specific organization.

GET /api/organizations/{id}

Parameters¶

Parameter	Type	Description
`id`	UUID	Organization ID

Response¶

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-org",
  "platform": "github",
  "external": false,
  "sync_status": "completed",
  "last_sync": "2026-02-28T10:30:00Z",
  "repo_count": 42,
  "health_score": 85,
  "stats": {
    "commits_30d": 150,
    "prs_30d": 25,
    "issues_30d": 10,
    "contributors_30d": 12
  }
}

Delete Organization¶

Remove an organization from monitoring.

DELETE /api/organizations/{id}

Parameters¶

Parameter	Type	Description
`id`	UUID	Organization ID

Response¶

Status: 204 No Content

Warning

This also removes all associated repositories and activity data.

Trigger Sync¶

Manually trigger a sync for an organization.

POST /api/organizations/{id}/sync

Parameters¶

Parameter	Type	Description
`id`	UUID	Organization ID

Response¶

{
  "message": "Sync started",
  "sync_status": "in_progress"
}

Status: 202 Accepted

Rate Limiting¶

Sync triggers are rate limited to 5 per minute per organization.

Get Organization Repositories¶

List repositories for an organization.

GET /api/organizations/{id}/repositories

Query Parameters¶

Parameter	Type	Default	Description
`limit`	integer	50	Max results
`offset`	integer	0	Pagination offset
`sort`	string	`name`	Sort field

Response¶

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "repo-name",
      "full_name": "my-org/repo-name",
      "description": "A great repository",
      "stars": 100,
      "forks": 20,
      "health_score": 90
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Example: Add and Sync Organization¶

import httpx

client = httpx.Client(
    base_url="http://localhost:8000/api",
    headers={"Authorization": f"Bearer {token}"}
)

# Add organization
response = client.post("/organizations/", json={
    "name": "python",
    "platform": "github",
    "external": True  # Monitor external org
})
org = response.json()
print(f"Added organization: {org['id']}")

# Trigger sync
client.post(f"/organizations/{org['id']}/sync")
print("Sync started")

# Check sync status
response = client.get(f"/organizations/{org['id']}")
org = response.json()
print(f"Sync status: {org['sync_status']}")