Cogveo API Documentation

Authentication

All API requests require a Bearer token. Generate an API key from your Cogveo dashboard or via the API.

API Key Format

Keys start with cgv_ and are shown once on creation. Store them securely.

Authorization: Bearer cgv_abc123...

Permissions

API keys inherit the permissions of the user who created them. Each endpoint requires a specific permission based on the user's workspace role.

Errors

All errors return JSON with an error field.

{ "error": "Invalid API key" }

Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing API key
403	Forbidden — insufficient permissions
404	Not found — resource doesn't exist
429	Rate limited — too many requests
500	Server error

API Keys

Manage API keys for programmatic access. Keys are created using your session token (Cognito auth), not an API key.

POST /keys Generate a new API key

Auth: Session token (not API key)

Request Body

Param	Type		Description
name	string	optional	Key name (default: "API Key")

Response

201
{
  "key": "cgv_abc123...",
  "prefix": "cgv_abc123",
  "name": "My CI Key",
  "message": "Save this key — it cannot be shown again."
}

GET /keys List API keys (masked)

Auth: Session token

Response

200
{
  "keys": [
    { "id": "uuid", "name": "My Key", "key_prefix": "cgv_abc123",
      "last_used_at": "2026-04-06T...", "created_at": "2026-04-05T..." }
  ]
}

DELETE /keys/:keyId Revoke an API key

Auth: Session token

Response

200 { "success": true }

Files

Upload, download, list, and delete files in your workspace.

GET /files List directory or download file

FILES_READ

Query Parameters

Param	Type		Description
workspace	string	required	Workspace ID
path	string	optional	File or folder path. If file, downloads it. If folder, lists contents.

Response (directory)

200
{
  "items": [
    { "name": "report.pdf", "type": "file", "path": "report.pdf", "size": 45032 },
    { "name": "Outputs", "type": "directory", "path": "Outputs" }
  ]
}

Response (file)

Binary file download with Content-Disposition header

POST /files/upload Upload a file

FILES_UPLOAD

Request (multipart/form-data)

Param	Type		Description
workspace	string	required	Workspace ID
file	file	required	File to upload (max 500MB)
path	string	optional	Target subdirectory

Example

curl -X POST /api/v1/files/upload \
  -H "Authorization: Bearer cgv_..." \
  -F "workspace=<id>" \
  -F "file=@data.csv" \
  -F "path=input/"

Response

200
{ "success": true, "path": "input/data.csv", "size": 12345 }

DELETE /files Delete file or folder

FILES_DELETE

Query Parameters

Param	Type		Description
workspace	string	required	Workspace ID
path	string	required	File or folder path

Response

200 { "success": true }

POST /files/unzip Extract a ZIP file in place

FILES_CREATE

Request Body

Param	Type		Description
workspace	string	required	Workspace ID
path	string	required	Path to the ZIP file

Response

200
{ "success": true, "extracted_to": "data/" }

Skills

List available skills in a workspace.

GET /skills List workspace skills

SKILLS_READ

Query Parameters

workspace

string

required

Workspace ID

Response

200
{
  "skills": [
    { "id": "uuid", "name": "Resume Analyzer", "content": "...",
      "is_global": false, "created_at": "2026-04-05T..." }
  ]
}

Skill Runs

Trigger skills to run autonomously. Each run executes in an isolated Docker sandbox.

POST /skill-runs Trigger a skill run

SKILL_RUNS_CREATE

Request Body

Param	Type		Description
workspace	string	required	Workspace ID
skill_id	string	required	Skill to execute
instructions	string	optional	Additional instructions for this run
context_paths	string[]	optional	Files/folders to read as context
notify_emails	string[]	optional	Emails to notify on completion

Example

curl -X POST /api/v1/skill-runs \
  -H "Authorization: Bearer cgv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "ws-uuid",
    "skill_id": "skill-uuid",
    "instructions": "Focus on Q1 metrics",
    "context_paths": ["sales_q1.csv"],
    "notify_emails": ["team@company.com"]
  }'

Response

202
{
  "run_id": "run-uuid",
  "status": "running",
  "message": "Skill run started. Poll GET /api/v1/skill-runs/:runId for status."
}

GET /skill-runs/:runId Get run status and output

SKILL_RUNS_READ

Response

200
{
  "run": {
    "id": "run-uuid",
    "status": "completed",
    "skill_name": "Resume Analyzer",
    "model": "gemini-2.5-flash",
    "input_tokens": 1234,
    "output_tokens": 567,
    "cost_usd": "0.000320",
    "console_output": "...",
    "started_at": "2026-04-06T...",
    "completed_at": "2026-04-06T..."
  },
  "output_files": ["analysis.docx", "summary.csv"]
}

GET /skill-runs/:runId/download Download output files as ZIP

SKILL_RUNS_READ

Response

Binary ZIP file download
Content-Type: application/zip
Content-Disposition: attachment; filename="run-abc123-output.zip"

Example

curl /api/v1/skill-runs/run-uuid/download \
  -H "Authorization: Bearer cgv_..." \
  -o output.zip

Schedules

Automate skill runs on a recurring cron schedule.

GET /schedules List schedules

SKILL_RUNS_READ

Query Parameters

workspace

string

required

Workspace ID

Response

200
{
  "schedules": [
    {
      "id": "sched-uuid",
      "name": "Weekly Sales Report",
      "skill_name": "Sales Analyzer",
      "cron_expression": "0 9 * * 1",
      "timezone": "America/New_York",
      "enabled": true,
      "next_run_at": "2026-04-07T13:00:00Z",
      "run_count": 12
    }
  ]
}

POST /schedules Create a schedule

SKILL_RUNS_CREATE

Request Body

Param	Type		Description
workspace	string	required	Workspace ID
skill_id	string	required	Skill to schedule
name	string	required	Schedule name
cron_expression	string	required	Cron expression (5-field)
timezone	string	optional	IANA timezone (default: America/New_York)
instructions	string	optional	Additional run instructions
context_paths	string[]	optional	Context files
notify_emails	string[]	optional	Notification emails

Cron Presets

Expression	Meaning
`0 * * * *`	Every hour
`0 9 * * *`	Daily at 9:00 AM
`0 9 * * 1`	Every Monday at 9:00 AM
`0 9 * * 1-5`	Weekdays at 9:00 AM
`0 9 1 * *`	1st of month at 9:00 AM

Example

curl -X POST /api/v1/schedules \
  -H "Authorization: Bearer cgv_..." \
  -H "Content-Type: application/json" \
  -d '{
    "workspace": "ws-uuid",
    "skill_id": "skill-uuid",
    "name": "Weekly Report",
    "cron_expression": "0 9 * * 1",
    "timezone": "America/New_York",
    "notify_emails": ["team@company.com"]
  }'

POST /schedules/:scheduleId/toggle Pause or resume a schedule

SKILL_RUNS_CREATE

Response

200 { "enabled": false }

POST /schedules/:scheduleId/run-now Manually trigger a scheduled run

SKILL_RUNS_CREATE

Response

200 { "triggered": true }

DELETE /schedules/:scheduleId Delete a schedule

SKILL_RUNS_CANCEL

Response

200 { "success": true }

Rate Limits

API requests are rate-limited per API key. Skill runs are subject to LLM provider rate limits.

Endpoint	Limit
File operations	100 req/min
Skill runs	10 req/min
Schedule operations	30 req/min

When rate limited, you'll receive a 429 status. Retry after the Retry-After header value.

Cogveo REST API

Getting Started

API Keys

Files

Skills

Skill Runs

Schedules

Authentication

API Key Format

Permissions

Errors

API Keys

Auth: Session token (not API key)

Request Body

Response

Auth: Session token

Response

Auth: Session token

Response

Files

Query Parameters

Response (directory)

Response (file)

Request (multipart/form-data)

Example

Response

Query Parameters

Response

Request Body

Response

Skills

Query Parameters

Response

Skill Runs

Request Body

Example

Response

Response

Response

Example

Schedules

Query Parameters

Response

Request Body

Cron Presets

Example

Response

Response

Response

Rate Limits