Working with Jobs

Jobs are the core execution unit in Knify. Each job runs your agentic workload in an isolated sandbox with full state persistence.

Job Types

Knify supports multiple job types to match your use case:

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "cursor_task",
      "prompt": "Analyze this codebase and suggest optimizations",
      "model": "sonnet-4.5",
      "workspace_path": "/workspaces/my-project"
    }
  }'

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "fh_e2e_tools",
      "prompt": "Create a test user using the runbook @create-user.md",
      "workspace_path": "/workspaces/e2e-tests"
    }
  }'

curl -X POST https://api.knify.io/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "user_exam",
      "user_id": "user_12345",
      "time_range": {
        "from": "2025-01-01T00:00:00Z",
        "to": "2025-01-31T23:59:59Z"
      }
    }
  }'

Job Lifecycle

Managing Jobs

List All Jobs

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

Get Job Details

curl https://api.knify.io/jobs/{job_id} \
  -H "Authorization: Bearer $KNIFY_API_KEY"

Response includes:

• Full job specification
• Current status and timestamps
• Execution events (with timestamps and details)
• Sandbox ID (for continuation)
• Error information (if failed)
• Cursor session ID (for conversation continuity)

Get Job Events

Monitor real-time progress:

curl https://api.knify.io/jobs/{job_id}/events \
  -H "Authorization: Bearer $KNIFY_API_KEY"

Event types:

• sandbox_created - Sandbox provisioned
• workspace_mounted - Files uploaded to sandbox
• agent_started - AI agent execution began
• artifact_generated - Output files created
• sandbox_paused - Sandbox paused (ready for continuation)

Stream Cursor Output

For Cursor tasks, watch the agent's work in real-time:

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

Uses Server-Sent Events (SSE) for live streaming.

Job Continuation

Jobs can be continued to build multi-step workflows or iterative conversations:

curl -X POST https://api.knify.io/jobs/{job_id}/continue \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $KNIFY_API_KEY" \
  -d '{
    "spec": {
      "job_type": "cursor_task",
      "prompt": "Now add tests for the code you just wrote"
    }
  }'

Continuation Benefits:

• Reuses the same sandbox (fast startup)
• Preserves all files and state
• Maintains conversation context
• Keeps Cursor session history

Artifact Retrieval

Fetch generated files and reports:

curl https://api.knify.io/jobs/{job_id}/artifacts \
  -H "Authorization: Bearer $KNIFY_API_KEY"

Common artifacts:

• result.json - Structured output data
• report.md - Human-readable report
• Generated code files
• Test results
• Screenshots (for E2E jobs)

Cleanup

When done with a job, free the sandbox resources:

curl -X POST https://api.knify.io/jobs/{job_id}/cleanup \
  -H "Authorization: Bearer $KNIFY_API_KEY"

Job Configuration Options

Workspace Path

Specify a custom workspace to use:

{
  "spec": {
    "job_type": "cursor_task",
    "prompt": "Your task",
    "workspace_path": "/workspaces/my-project"
  }
}

Model Selection

Choose a specific AI model:

{
  "spec": {
    "job_type": "cursor_task",
    "prompt": "Your task",
    "model": "sonnet-4.5"
  }
}

Session ID

Resume a previous Cursor conversation:

{
  "spec": {
    "job_type": "cursor_task",
    "prompt": "Continue from where we left off",
    "session_id": "session_xyz"
  }
}

Metadata

Attach custom metadata to jobs:

{
  "spec": {
    "job_type": "cursor_task",
    "prompt": "Your task",
    "metadata": {
      "user_id": "user_123",
      "team": "engineering",
      "priority": "high"
    }
  }
}

Best Practices

1. Use Continuation: Instead of creating new jobs, continue existing ones for faster execution
2. Monitor Events: Stream events to track progress and debug issues
3. Cleanup Resources: Call /cleanup when jobs are truly complete
4. Leverage Metadata: Tag jobs for easy tracking and analytics
5. Choose Models Wisely: Use auto for general tasks, specific models for specialized needs