API Reference

Complete reference for the Knify API.

Base URL

https://api.knify.io

For self-hosted instances, use your configured base URL.

Authentication

All API requests require authentication via the Authorization header:

Authorization: Bearer your_api_key_here

Obtaining API Keys:

Contact your administrator
Or generate via the Knify dashboard

HTTP Status Codes:

401 Unauthorized - Missing or invalid API key
403 Forbidden - Insufficient permissions

Endpoints

Health Check

GET /

Check if the API is running.

Response:

{
  "status": "ok",
  "version": "0.1.0"
}

Create Job

POST /jobs

Create and start a new job.

Request Body:

{
  "spec": {
    "job_type": "cursor_task",
    "prompt": "Your task description",
    "model": "sonnet-4.5",
    "workspace_path": "/workspaces/my-project",
    "session_id": "session_123",
    "metadata": {
      "user_id": "user_123",
      "priority": "high"
    }
  }
}

Parameters:

Field	Type	Required	Description
`job_type`	string	Yes	Job type: `cursor_task`, `gemini_task`, `claude_task`
`prompt`	string	Conditional	Task description (required for cursor_task)
`model`	string	No	AI model: `auto`, `sonnet-4.5`, `opus-4.1`, `composer-1`, `gpt-5`
`workspace_path`	string	No	Path to workspace in Knify
`session_id`	string	No	Resume previous Cursor session
`user_id`	string	Conditional	User ID (required for user_exam)
`time_range`	object	Conditional	Time range (required for user_exam)
`metadata`	object	No	Custom metadata

Response:

{
  "job_id": "job_abc123",
  "status": "running"
}

Status Codes:

200 OK - Job created successfully
400 Bad Request - Invalid job specification
401 Unauthorized - Missing/invalid API key

List Jobs

GET /jobs

List all jobs.

Response:

[
  {
    "id": "job_abc123",
    "spec": { ... },
    "status": "completed",
    "created_at": "2025-11-17T10:00:00Z",
    "started_at": "2025-11-17T10:00:01Z",
    "completed_at": "2025-11-17T10:05:30Z",
    "sandbox_id": "sandbox_xyz",
    "cursor_session_id": "session_123"
  },
  ...
]

Get Job Details

GET /jobs/{job_id}

Get detailed information about a specific job.

Response:

{
  "id": "job_abc123",
  "spec": {
    "job_type": "cursor_task",
    "prompt": "Write a Python script",
    "model": "sonnet-4.5"
  },
  "status": "completed",
  "created_at": "2025-11-17T10:00:00Z",
  "started_at": "2025-11-17T10:00:01Z",
  "completed_at": "2025-11-17T10:05:30Z",
  "sandbox_id": "sandbox_xyz789",
  "cursor_session_id": "session_abc",
  "events": [
    {
      "ts": "2025-11-17T10:00:01Z",
      "stage": "sandbox_created",
      "level": "info",
      "detail": "Sandbox provisioned"
    },
    {
      "ts": "2025-11-17T10:00:05Z",
      "stage": "agent_started",
      "level": "info",
      "detail": "Cursor agent executing"
    },
    {
      "ts": "2025-11-17T10:05:30Z",
      "stage": "completed",
      "level": "info",
      "detail": "Job completed successfully"
    }
  ],
  "artifacts": {
    "files": ["fibonacci.py", "test.py"]
  },
  "error": null
}

Status Codes:

200 OK - Job found
404 Not Found - Job ID doesn't exist

Get Job Events

GET /jobs/{job_id}/events

Get progress events for a job.

Response:

{
  "events": [
    {
      "ts": "2025-11-17T10:00:01Z",
      "stage": "sandbox_created",
      "level": "info",
      "detail": "Sandbox provisioned"
    },
    ...
  ]
}

Get Job Artifacts

GET /jobs/{job_id}/artifacts

Get generated files and outputs from a job.

Response:

{
  "result.json": {
    "status": "success",
    "data": { ... }
  },
  "report.md": "# Analysis Report\n\n...",
  "fibonacci.py": "def fib(n):\n    ..."
}

Get Cursor Output

GET /jobs/{job_id}/cursor

Get full Cursor agent output (for cursor_task jobs).

Response:

{
  "events": [
    {
      "type": "agent_message",
      "message": "I'll create a fibonacci script",
      "timestamp": "2025-11-17T10:00:05Z"
    },
    {
      "type": "tool_use",
      "tool": "write_file",
      "parameters": {
        "path": "fibonacci.py",
        "content": "..."
      },
      "timestamp": "2025-11-17T10:00:10Z"
    },
    ...
  ]
}

Stream Cursor Output

GET /jobs/{job_id}/cursor/stream

Stream Cursor output in real-time using Server-Sent Events (SSE).

Example (curl):

curl -N https://api.knify.io/jobs/job_abc123/cursor/stream \
  -H "Authorization: Bearer $KNIFY_API_KEY"

Example (JavaScript):

const eventSource = new EventSource(
  'https://api.knify.io/jobs/job_abc123/cursor/stream',
  {
    headers: {
      'Authorization': 'Bearer ' + apiKey
    }
  }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Cursor event:', data);
};

eventSource.onerror = (error) => {
  console.error('Stream error:', error);
  eventSource.close();
};

Continue Conversation

POST /jobs/{job_id}/continue

Continue a Cursor conversation from a previous job.

Request Body:

{
  "spec": {
    "job_type": "cursor_task",
    "prompt": "Now add tests for the code you wrote"
  }
}

Response:

{
  "job_id": "job_def456",
  "status": "running",
  "parent_job_id": "job_abc123",
  "sandbox_id": "sandbox_xyz789",
  "cursor_session_id": "session_abc"
}

The new job reuses the same sandbox and Cursor session.

Cleanup Sandbox

POST /jobs/{job_id}/cleanup

Permanently delete the sandbox and free resources.

Response:

{
  "success": true,
  "message": "Sandbox cleaned up successfully"
}

Cleanup is permanent. You cannot continue a job after cleanup.

Web Console

GET /console

Access the web-based monitoring console.

Opens an HTML interface for viewing job status, events, and logs in real-time.

Error Responses

All errors follow a consistent format:

{
  "error": "Error message",
  "detail": "Additional context",
  "code": "ERROR_CODE"
}

Common Error Codes:

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource doesn't exist
`BAD_REQUEST`	400	Invalid request parameters
`INTERNAL_ERROR`	500	Server error
`SANDBOX_ERROR`	500	Sandbox creation/execution failed

Rate Limits

API requests are rate limited:

Free Tier: 100 requests/hour
Pro Tier: 1,000 requests/hour
Enterprise: Custom limits

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1635724800

Pagination

List endpoints support pagination:

GET /jobs?page=2&limit=50

Parameters:

page - Page number (default: 1)
limit - Items per page (default: 20, max: 100)

Response includes:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 245,
    "pages": 5
  }
}

OpenAPI Specification

Download the full OpenAPI spec:

GET /openapi.json

Use with tools like Postman, Insomnia, or generate SDKs with OpenAPI Generator.

Back to Overview

Return to the introduction.