Cogram API

The Cogram API allows you to programmatically integrate Cogram with your own systems and workflows. Use it to automate project management, synchronize user data, and build custom integrations.

Overview

Cogram provides a RESTful API served from a dedicated subdomain (api.cogram.com). It uses API key authentication and provides stable, versioned endpoints designed for third-party integrations.

Key features:

• Stable versioned endpoints - The API is versioned (/v1/) to ensure backwards compatibility

• Interactive documentation - Explore and test endpoints directly at api.cogram.com/v1/docs

• External ID mapping - Link Cogram resources to your own system's identifiers

Authentication

The Cogram API uses API key authentication. API keys are organization-scoped and can be created by organization administrators.

Creating an API Key

1. Go to Settings > Administration > Integrations > API Keys in the Cogram app.

2. Click Create API Key.

3. Give your key a descriptive name and optionally set an expiration date.

4. Copy the key immediately — it will only be shown once.

Using Your API Key

Include the API key in the Authorization header as a Bearer token:

curl example

curl -X GET "https://api.cogram.com/v1/projects" \
  -H "Authorization: Bearer YOUR_API_KEY"

Optional Headers

X-Forwarded-User

Identifier of the user in your system (e.g., user ID or email) who triggered this action. When provided, Cogram's audit logs will attribute the action to this user rather than just the API key. Omit for automated system tasks with no associated user.

Base URL

All API requests should be made to:

https://api.cogram.com

Available Endpoints

Projects

Manage projects within your organization.

Method	Endpoint	Description
GET	/v1/projects	List all projects
POST	/v1/projects	Create a new project
GET	/v1/projects/{id}	Get a specific project
PATCH	/v1/projects/{id}	Update a project
DELETE	/v1/projects/{id}	Archive a project

Project Members

Manage project membership and roles.

Method	Endpoint	Description
GET	/v1/projects/{id}/members	List project members
PUT	/v1/projects/{id}/members/{user_id}	Add or update a member
DELETE	/v1/projects/{id}/members/{user_id}	Remove a member

Users

Manage organization members.

Method	Endpoint	Description
GET	/v1/users	List organization members
PATCH	/v1/users/{user_id}	Update a user's role

Rate Limiting

API requests are rate limited on a per-key basis. The default limit is 1000 requests per minute.

When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating when you can retry.

Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format:

error example

{
  "error": "error_code",
  "message": "Human-readable description"
}

Common Error Codes

HTTP Status	Error Code	Description
401	api_key_missing	No API key provided
401	api_key_invalid	API key not found or incorrect
401	api_key_expired	API key has expired
404	not_found	Resource does not exist
409	conflict	Resource already exists
422	validation_error	Invalid request body
429	rate_limit_exceeded	Too many requests

This is not an exhaustive list. For all possible error responses per each endpoint and all error codes, see the interactive documentation at api.cogram.com/v1/docs.

Pagination

List endpoints support pagination using query parameters:

Parameter	Default	Max	Description
page	1	-	Page number (1-indexed)
page_size	50	100	Number of items per page

Example:

curl example

curl "https://api.cogram.com/v1/projects?page=2&page_size=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paginated response format:

paginated response

{
  "data": [...],
  "total": 150,
  "page": 2,
  "page_size": 25
}

API Reference

For detailed endpoint documentation, request/response schemas, error codes and an interactive API explorer, visit:

api.cogram.com/v1/docs

Security Best Practices

• Keep your API keys secret - Never expose them in client-side code or public repositories

• Use environment variables - Store API keys in environment variables, not in code

• Rotate keys regularly - Create new keys and revoke old ones periodically

• Use descriptive names - Name your keys by their purpose to track usage

• Revoke unused keys - Delete keys that are no longer needed

Support

Contact support through the Cogram app if you have questions or need help with the Cogram API.