Public API

Integrate your applications with Corcava using our RESTful Public API. Build custom integrations, automate workflows, and connect Corcava with your existing tools and systems.

Overview

The Corcava Public API provides programmatic access to your core business data including projects, tasks, boards, clients, contacts, and tickets. Use standard HTTP methods to create, read, update, and delete resources, enabling powerful automation and integration capabilities.

Getting Started

Generate Your API Key

1. Navigate to Settings → Integrations
2. Scroll to the Public API section
3. Click Generate API Key
4. Copy your API key immediately - it's only shown once for security
5. Store it securely - you'll need it for all API requests

API Key Management

You can manage multiple API keys from the Integrations page:

• Create new keys - Generate additional keys for different applications or environments
• Activate/Deactivate - Toggle keys on or off without deleting them
• Delete keys - Permanently remove keys you no longer need

Best Practice: Create separate API keys for different applications or environments (development, staging, production) to better manage access and security.

Base URL

All API requests should be made to:

https://corcava.com/api/v1

For development/testing environments, use your specific domain:

https://your-domain.com/api/v1

Authentication

Include your API key in every request using the Authorization header:

Authorization: Bearer YOUR_API_KEY_HERE

Example Request:

curl -X GET "https://corcava.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Accept: application/json"

Available Endpoints

The Public API provides full CRUD (Create, Read, Update, Delete) access to your core business resources including projects, tasks, boards, clients, contacts, and tickets. Each resource supports standard REST operations with filtering, searching, and pagination capabilities.

For complete endpoint documentation, request/response examples, and detailed parameter specifications, visit the interactive API documentation:

https://corcava.com/api/v1/docs

The interactive documentation provides:

• Complete list of all available endpoints
• Detailed request and response examples
• Parameter descriptions and validation rules
• Authentication requirements
• Ability to test API calls directly from your browser

Request Format

Headers

All requests should include:

• Authorization: Bearer YOUR_API_KEY - Required for authentication
• Accept: application/json - Specifies JSON response format
• Content-Type: application/json - Required for POST/PUT requests with body

Query Parameters

Most list endpoints support filtering, searching, and pagination:

• search - Search by name or other searchable fields
• per_page - Number of results per page (default: 30, max: 100)
• page - Page number for pagination
• sort - Column to sort by (e.g., name, created_at)
• direction - Sort direction: asc or desc

Example: GET /api/v1/projects?search=onboarding&per_page=50&sort=created_at&direction=desc

Response Format

Successful responses return JSON with the following structure:

{
  "data": [
    {
      "id": 1,
      "name": "Project Name",
      ...
    }
  ],
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  },
  "meta": {
    "current_page": 1,
    "per_page": 30,
    "total": 100
  }
}

Error responses include details about what went wrong:

{
  "message": "Validation error",
  "errors": {
    "field_name": ["Error message 1", "Error message 2"]
  }
}

Common Use Cases

Automate Project Creation

Create projects automatically when new clients are added to your CRM:

curl -X POST "https://corcava.com/api/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onboarding Project",
    "client_id": 5,
    "user_id": 12,
    "billable": true
  }'

Sync Tasks from External Tools

Import tasks from project management tools or create tasks based on external events:

curl -X POST "https://corcava.com/api/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review design mockups",
    "board_id": 3,
    "user_id": 8
  }'

Build Custom Dashboards

Fetch data to build custom reporting dashboards or integrate with business intelligence tools:

curl -X GET "https://corcava.com/api/v1/projects?per_page=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhook Integration

Use the API to sync data when webhooks are triggered from external systems, keeping your Corcava data up-to-date automatically.

Rate Limits

API requests are subject to rate limiting to ensure fair usage and system stability. If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Best Practice: Implement exponential backoff and retry logic in your integration to handle rate limits gracefully.

Error Handling

The API uses standard HTTP status codes:

• 200 OK - Request successful
• 201 Created - Resource created successfully
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - API key doesn't have permission
• 404 Not Found - Resource doesn't exist
• 422 Unprocessable Entity - Validation errors
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Always check the response status code and handle errors appropriately in your integration.

Team Isolation

All API requests are automatically scoped to your team. You can only access resources (projects, tasks, clients, etc.) that belong to your team. This ensures data security and prevents cross-team data access.

Security Best Practices

1. Store API keys securely - Never commit API keys to version control or expose them in client-side code
2. Use environment variables - Store keys in environment variables or secure configuration files
3. Rotate keys regularly - Generate new keys periodically and revoke old ones
4. Use separate keys per application - Don't reuse the same key across multiple integrations
5. Monitor key usage - Regularly review which keys are active and delete unused ones
6. Use HTTPS only - Always make API requests over HTTPS, never HTTP

Support

Need help with the API? Check out the interactive documentation at /api/v1/docs or reach out to our support team. We're here to help you build powerful integrations that streamline your workflow.