Knaps API Overview

The Knaps API allows you to programmatically create, read, update, and delete Knaps (automated workflows) for your users.

Base URL

https://api.knapsack.ai/api/studio/knap-tools

Authentication

All API requests require authentication using a Client ID and Client Secret. Include your credentials in the request headers:

Authorization: Bearer {access_token}

To obtain an access token, see Authentication.

Running Knaps

Once you've created a Knap, you can execute it programmatically to perform automated workflows with your connected tools and data. The Knap Runs API allows you to:

• Execute agents on-demand - Trigger Knap workflows via API calls
• Stream real-time results - Receive live updates as the agent executes
• Provide custom context - Pass dynamic data and instructions to your agents
• Handle tool interactions - Monitor and respond to tool executions
• Continue conversations - Maintain context across multiple requests

For detailed information on executing Knaps programmatically, including request formats, streaming responses, and code examples, see the Knap Runs documentation.

Common Concepts

Knap Types

Knaps can have different schedule types that determine when they execute:

• manual - Executed on-demand by the user
• scheduled - Executed automatically based on a schedule
• post_meeting_transcription - Triggered after meeting transcriptions complete

Visibility

Knaps have different visibility levels:

• private - Only visible to the creator
• public - Visible to all users in the Public organization
• {org_name} - Visible to all users in a specific organization

Scheduling with Natural Language

For scheduled Knaps, specify the schedule using natural language in the tool_metadata.schedule_description field. The system will automatically parse and set up the schedule.

Examples:

• "every Monday at 9am"
• "daily at 2:30 PM"
• "every Thursday at 11 AM"
• "15th of every month at 10:00"
• "first Monday of every month"
• "every March 15th at 2 PM"

The API will automatically parse these descriptions and create the appropriate schedule.

Rate Limiting

API requests are rate limited to 100 requests per minute per client ID.

Error Handling

The API uses standard HTTP status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 500 - Internal Server Error

Error responses include a JSON body with details:

{
  "detail": "Error message describing what went wrong"
}