API Reference

Complete REST API documentation for Verk. Build integrations, automate workflows, and extend platform capabilities.

API Overview

Base URL: https://api.verk.com/v1

Authentication: Bearer token (API key)

Format: JSON request and response bodies

Rate limiting: Based on plan tier

Versioning: URL-based (/v1, /v2)

Authentication

All API requests require authentication:

curl -H "Authorization: Bearer YOUR_API_KEY" \
 https://api.verk.com/v1/tasks

Get API keys from Settings → API Keys. See API Keys documentation.

Tasks API

List Tasks

GET /tasks

Retrieve all tasks you have access to.

Query parameters:

• projectId (string): Filter by project
• status (string): Filter by status (todo, in_progress, done)
• assigneeId (string): Filter by assignee
• priority (string): Filter by priority (low, medium, high)
• limit (number): Results per page (default: 50, max: 100)
• offset (number): Pagination offset

Example request:

curl -X GET "https://api.verk.com/v1/tasks?status=in_progress&limit=20" \
 -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "data": [
    {
      "id": "task_123",
      "title": "Implement user authentication",
      "description": "Add OAuth2 login",
      "status": "in_progress",
      "priority": "high",
      "projectId": "proj_456",
      "assigneeId": "user_789",
      "creatorId": "user_101",
      "dueDate": "2024-12-31T23:59:59Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:45:00Z"
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

Create Task

POST /tasks

Create a new task.

Request body:

{
  "title": "Task title (required)",
  "description": "Task description (optional)",
  "projectId": "proj_123 (required)",
  "priority": "high|medium|low (optional, default: medium)",
  "status": "todo|in_progress|done (optional, default: todo)",
  "assigneeId": "user_456 (optional)",
  "dueDate": "2024-12-31T23:59:59Z (optional)",
  "customFields": {
    "field_name": "field_value"
  }
}

Example:

curl -X POST "https://api.verk.com/v1/tasks" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "title": "Design homepage mockup",
 "projectId": "proj_123",
 "priority": "high",
 "assigneeId": "user_456",
 "dueDate": "2024-02-15T17:00:00Z"
 }'

Update Task

PATCH /tasks/{taskId}

Update an existing task.

Request body: (all fields optional)

{
  "title": "Updated title",
  "status": "in_progress",
  "priority": "low",
  "assigneeId": "user_789"
}

Delete Task

DELETE /tasks/{taskId}

Permanently delete a task.

Projects API

List Projects

GET /projects

Get all projects in your organization.

Query parameters:

• archived (boolean): Include archived projects
• limit (number): Results per page
• offset (number): Pagination offset

Create Project

POST /projects

Request body:

{
  "name": "Project name (required)",
  "description": "Project description (optional)",
  "icon": "icon_name (optional)",
  "color": "#hex_color (optional)"
}

Update Project

PATCH /projects/{projectId}

Delete Project

DELETE /projects/{projectId}

Members API

List Members

GET /members

Get organization members.

Invite Member

POST /members/invite

Request body:

{
  "email": "user@example.com",
  "role": "admin|member|guest"
}

Comments API

List Comments

GET /tasks/{taskId}/comments

Create Comment

POST /tasks/{taskId}/comments

Request body:

{
  "content": "Comment text",
  "mentions": ["user_123", "user_456"]
}

Files API

Upload File

POST /files

Request: multipart/form-data

curl -X POST "https://api.verk.com/v1/files" \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -F "file=@document.pdf" \
 -F "projectId=proj_123"

Download File

GET /files/{fileId}/download

Returns presigned URL for file download.

Webhooks API

List Webhooks

GET /webhooks

Create Webhook

POST /webhooks

Request body:

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

Error Handling

Error response format:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: title",
    "param": "title",
    "type": "validation_error"
  }
}

Status codes:

• 200 Success
• 201 Created
• 400 Bad request
• 401 Unauthorized
• 403 Forbidden
• 404 Not found
• 429 Rate limit exceeded
• 500 Server error

Rate Limiting

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1640995200

Limits:

• Free: 1,000/day
• Pro: 100,000/day
• Enterprise: Custom

Pagination

All list endpoints support pagination:

Request:

GET /tasks?limit=50&offset=0

Response:

{
 "data": [...],
 "pagination": {
 "total": 500,
 "limit": 50,
 "offset": 0,
 "hasMore": true
 }
}

Webhooks

Subscribe to real-time events:

Events:

• task.created
• task.updated
• task.deleted
• task.completed
• project.created
• project.updated
• member.added
• comment.created

Webhook payload:

{
 "event": "task.created",
 "timestamp": "2024-01-15T10:30:00Z",
 "data": {
 "id": "task_123",
 "title": "New task",
 ...
 }
}

See Webhooks documentation for details.

SDKs

Official libraries available:

• JavaScript/TypeScript: npm install @verk/sdk
• Python: pip install verk-sdk
• Go: go get github.com/verk/go-sdk

See SDK documentation.

Best Practices

Use Pagination Always paginate large result sets to improve performance.

Handle Rate Limits Implement exponential backoff when hitting rate limits.

Validate Webhooks Verify webhook signatures to ensure authenticity.

Cache Responses Cache API responses when data doesn't change frequently.

Use Webhooks Subscribe to webhooks instead of polling for changes.

Test in Sandbox Use test API keys during development.

Monitor Usage Track API usage in dashboard to avoid surprises.

Related Documentation

• API Keys - Authentication setup
• Webhooks - Event subscriptions
• SDK - Client libraries
• Customization - Advanced integration

---

Need developer support? Check our developer forum or contact support.