Developer FAQ
API - General
Section titled “API - General”What is the API base URL?
Section titled “What is the API base URL?”The base URL follows the format of your Prodgy instance. All requests use JSON (UTF-8) as the data format. Interactive documentation is available via Swagger UI on your instance.
What resources are available in the API?
Section titled “What resources are available in the API?”The API offers 8 main resources:
| Resource | Description |
|---|---|
| Agents | Manage agents (list, create, update, delete) |
| Executions | Execute agents and query results |
| Integrations | Manage connections to external tools |
| Knowledge Base | Import documents and manage the knowledge base |
| Triggers | Configure automated triggers |
| Webhooks | Register and manage webhooks |
| Transcription | Transcribe audio (supported formats, max 25 MB) |
| API Tokens | Manage authentication tokens |
What are the rate limits?
Section titled “What are the rate limits?”- Standard: 10 requests per minute
- Strict: 5 requests per minute (for high-load endpoints)
When the limit is exceeded, the API returns status 429 Too Many Requests.
How does pagination work?
Section titled “How does pagination work?”Use the page, pageSize and limit parameters in list requests to control result pagination.
Authentication
Section titled “Authentication”How do I authenticate with the API?
Section titled “How do I authenticate with the API?”There are two authentication methods:
- API Token: for system integrations — send in the
X-API-TokenorAuthorization: Bearer {token}header - JWT: for authenticated user sessions
How do I create an API token?
Section titled “How do I create an API token?”Via interface: in Workspace Settings > API Tokens, click create. Via API: use the token creation endpoint. The token format is prodgy_{random_characters}.
Can I set expiration dates on tokens?
Section titled “Can I set expiration dates on tokens?”Yes. When creating or renewing a token, you can set an expiration date. Expired tokens stop working automatically.
How do I revoke or regenerate a token?
Section titled “How do I revoke or regenerate a token?”Use the revocation or regeneration API endpoints, or do it through the interface in API Tokens. When regenerating, the previous token is immediately invalidated.
How do I monitor token usage?
Section titled “How do I monitor token usage?”The API records audit logs for all token operations, including 6 action types: created, used, revoked, expired, renewed and regenerated.
What are the security best practices?
Section titled “What are the security best practices?”- Always use HTTPS
- Never expose tokens in source code or logs
- Set expiration dates
- Rotate tokens periodically
- Use different tokens per environment (dev, staging, production)
Webhooks
Section titled “Webhooks”What are webhooks in Prodgy?
Section titled “What are webhooks in Prodgy?”Webhooks allow external systems to send events to Prodgy via HTTP POST. The generic endpoint is POST /api/webhook/{custom_path}.
What format should the payload have?
Section titled “What format should the payload have?”The payload must be sent as JSON with Content-Type: application/json. The structure includes event metadata and specific data.
Are there specialized webhooks for communicators?
Section titled “Are there specialized webhooks for communicators?”Yes:
| Platform | Endpoint |
|---|---|
| Slack / Google Chat | /api/communicator/webhook/{integration_base_id} |
| Microsoft Teams | /api/communicator/botframework/{integration_base_id}/messages |
What are webhook best practices?
Section titled “What are webhook best practices?”- Validate received data before processing
- Respond quickly (avoid long processing in the request)
- Implement retries with exponential backoff
- Use HTTPS for all endpoints
- Monitor failures and configure alerts
Endpoints and Resources
Section titled “Endpoints and Resources”How do I execute an agent via API?
Section titled “How do I execute an agent via API?”Use the Executions endpoint with the agent ID and required parameters. The response includes the execution result or an ID for async querying.
How do I import documents via API?
Section titled “How do I import documents via API?”Use the Knowledge Base endpoints to upload files. Supported formats: CSV, PDF, DOCX, TXT, MD, JSON, XML. Maximum size: 50 MB per file.
How do I transcribe audio via API?
Section titled “How do I transcribe audio via API?”Send the audio file via multipart/form-data to the Transcription endpoint. Maximum size: 25 MB. The result is returned as text.
Where can I find the complete endpoint documentation?
Section titled “Where can I find the complete endpoint documentation?”Access Swagger UI on your Prodgy instance. There you will find all documented endpoints with request and response examples, and you can test directly.
MCP Gateway
Section titled “MCP Gateway”What is the MCP Gateway?
Section titled “What is the MCP Gateway?”The MCP Gateway is an MCP (Model Context Protocol) server that allows you to connect coding assistants like Claude Code, Cursor, and Windsurf to Prodgy. Through it, your AI assistant can access knowledge search tools, agents, integrations, and the workspace context.
How do I connect my coding assistant to the MCP Gateway?
Section titled “How do I connect my coding assistant to the MCP Gateway?”Add the MCP configuration in your client’s config file (.mcp.json for Claude Code, .cursor/mcp.json for Cursor, etc.) with your Prodgy URL followed by /mcp and your API Token in the authorization header. See MCP Gateway > Activating the MCP Server in the Developer Guide.
Do I need to install anything to use the MCP Gateway?
Section titled “Do I need to install anything to use the MCP Gateway?”No. The MCP Gateway is a remote HTTP service. Just configure the URL in your MCP client — no local installation is required.
What tools are available in the MCP Gateway?
Section titled “What tools are available in the MCP Gateway?”Tools are divided into two groups:
- Platform tools:
get_my_profile,get_workspace_info,update_my_ai_preferences,search_knowledge,list_agents,invoke_agent, integration catalog management, and MCP settings - Integration tools: dynamically loaded from your organization’s active integrations (e.g.,
create_ticket,list_issues,send_message)
What is workspace info and how is it injected?
Section titled “What is workspace info and how is it injected?”get_workspace_info returns a dynamic README of your workspace/product, assembled from the Main in Prodgy. It is automatically injected on the first tool call of each MCP session — together with get_my_profile for the authenticated user identity. You don’t need to call them explicitly.
How do I perform semantic search on the knowledge base?
Section titled “How do I perform semantic search on the knowledge base?”Use the search_knowledge tool with a natural language description of what you’re looking for. Prefer descriptive sentences over loose keywords. Adjust top_k as needed (3 for focused results, 10 for broad exploration).
How do I execute a Prodgy agent via MCP?
Section titled “How do I execute a Prodgy agent via MCP?”Use list_agents to discover available agents, and invoke_agent with the desired query. If you don’t specify an agent_id, Prodgy automatically selects the most appropriate agent.
What is the Integration Builder?
Section titled “What is the Integration Builder?”It’s the workflow that allows you to create integration templates directly from your coding assistant using create_integration. You describe the service you want to connect, the AI builds the complete template, and the administrator activates it in Prodgy with real credentials. The new tools automatically appear in the MCP for the entire organization.
Do I need a special role to manage integrations via MCP?
Section titled “Do I need a special role to manage integrations via MCP?”Yes. The tools create_integration, update_integration, delete_integration, get_mcp_settings, and update_mcp_settings require the SYSTEM role on the API Token.
Two integrations have tools with the same name. How do I resolve this?
Section titled “Two integrations have tools with the same name. How do I resolve this?”The Gateway automatically detects name collisions and adds an _integration parameter for disambiguation. The AI assistant receives a message listing the available options.
Troubleshooting
Section titled “Troubleshooting”I received a 401 error. What should I do?
Section titled “I received a 401 error. What should I do?”Verify that the token is correct, active and not expired. Confirm you are sending it in the X-API-Token or Authorization: Bearer {token} header.
I received a 429 error. What should I do?
Section titled “I received a 429 error. What should I do?”You have exceeded the rate limit. Wait before sending new requests. Consider implementing a retry mechanism with exponential backoff.
I received a 500 error. What should I do?
Section titled “I received a 500 error. What should I do?”Internal server error. Try again after a few seconds. If it persists, check the system logs or contact support at support@prodgy.ai.