API Overview

The GitScrum API provides programmatic access to your workspace data. Build custom integrations, automate workflows, create reports, or build entirely new interfaces on top of GitScrum.

Getting Started

Base URL

https://services.gitscrum.com/v1

Authentication

All requests require an API key in the header:

Authorization: Bearer your_api_key_here

Generate API Key

1. Go to Workspace Settings > API
2. Click "Generate API Key"
3. Name the key descriptively
4. Copy immediately (shown once only)
5. Store securely

Rate Limits

Rate limit headers in every response:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1705320000

Response Format

All responses are JSON:

{
  "data": { ... },
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 150
  }
}

Error Responses

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Task not found",
    "details": { ... }
  }
}

HTTP Status Codes

Core Endpoints

Workspaces

GET    /workspaces              # List your workspaces
GET    /workspaces/:id          # Get workspace details
PUT    /workspaces/:id          # Update workspace

Projects

GET    /workspaces/:id/projects         # List projects
POST   /workspaces/:id/projects         # Create project
GET    /projects/:id                     # Get project
PUT    /projects/:id                     # Update project
DELETE /projects/:id                     # Delete project

Tasks

GET    /projects/:id/tasks      # List tasks
POST   /projects/:id/tasks      # Create task
GET    /tasks/:id               # Get task
PUT    /tasks/:id               # Update task
DELETE /tasks/:id               # Delete task
PATCH  /tasks/:id/move          # Move task (change status)

Team Members

GET    /workspaces/:id/members  # List members
POST   /workspaces/:id/members  # Invite member
DELETE /members/:id             # Remove member

Time Entries

GET    /tasks/:id/time-entries  # List time for task
POST   /time-entries            # Create time entry
PUT    /time-entries/:id        # Update entry
DELETE /time-entries/:id        # Delete entry

Sprints

GET    /projects/:id/sprints    # List sprints
POST   /projects/:id/sprints    # Create sprint
PUT    /sprints/:id             # Update sprint
POST   /sprints/:id/start       # Start sprint
POST   /sprints/:id/end         # End sprint

Query Parameters

Pagination

GET /projects/:id/tasks?page=2&per_page=50

• page: Page number (default: 1)
• per_page: Items per page (default: 25, max: 100)

Filtering

GET /tasks?status=open&assignee=user_123&label=bug

Common filters:

• status: Task status
• assignee: User ID
• label: Label name
• priority: Priority level
• created_after: ISO date
• created_before: ISO date
• updated_after: ISO date

Sorting

GET /tasks?sort=created_at&order=desc

• sort: Field to sort by
• order: asc or desc

Including Relations

GET /tasks/:id?include=comments,time_entries,attachments

Reduces multiple requests by embedding related data.

Webhooks

Register webhooks to receive real-time updates:

POST /webhooks
{
  "url": "https://your-server.com/webhook",
  "events": ["task.created", "task.updated"],
  "secret": "your_signing_secret"
}

See Integrations Overview for event types.

Example: Create a Task

curl -X POST https://services.gitscrum.com/v1/projects/proj_123/tasks \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement login feature",
    "description": "Add OAuth2 login support",
    "priority": "high",
    "labels": ["feature", "auth"],
    "assignee_id": "user_456"
  }'

Response:

{
  "data": {
    "id": "task_789",
    "number": 42,
    "title": "Implement login feature",
    "status": "backlog",
    "priority": "high",
    "created_at": "2026-01-15T10:00:00Z",
    ...
  }
}

Example: Log Time

curl -X POST https://services.gitscrum.com/v1/time-entries \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "task_789",
    "duration_minutes": 90,
    "description": "Implemented OAuth flow",
    "billable": true,
    "date": "2026-01-15"
  }'

Example: Move Task

curl -X PATCH https://services.gitscrum.com/v1/tasks/task_789/move \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress"
  }'

SDKs and Libraries

Official

• JavaScript/TypeScript: npm install @gitscrum/sdk
• Python: pip install gitscrum

Community

Check our GitHub for community-maintained libraries.

OpenAPI Spec

Download the OpenAPI specification:

GET /openapi.json

Import into Postman, Insomnia, or generate clients.

Best Practices

Use Pagination

Never assume you can fetch all items. Always paginate.

Handle Rate Limits

Check X-RateLimit-Remaining and back off when low.

Cache When Possible

Use ETag headers for conditional requests.

Batch Operations

Where available, use batch endpoints to reduce requests.

Secure Your Keys

• Never commit keys to version control
• Use environment variables
• Rotate keys periodically
• Use separate keys per integration

Versioning

The API uses URL versioning (/v1/). Breaking changes only occur in new versions. Deprecation notices provided 6 months in advance.

Support

API Status

Check real-time status: status.gitscrum.com

Changelog

Updates and changes: docs.gitscrum.com/changelog

Support

For API issues, include:

• Request/response (sanitize keys)
• Endpoint called
• Timestamp
• Error message

How to Report a Problem or Request a Feature

If you encounter API issues or need additional endpoints, submit feedback through GitScrum Studio. In the Sidebar, click on Support Tickets and open a ticket.