API Reference

Complete reference for the TurtleApps REST API — 160 endpoints across 9 categories.

Base URL: https://app.turtleapps.nl/apiFormat: JSONAuth: Session / Bearer Token

Authentication

Session cookies or Bearer tokens for API access.

Webhooks

Real-time event notifications via HTTP callbacks.

Rate Limits

Per-plan rate limits to ensure fair usage.

Authentication

All authenticated endpoints require one of the following authentication methods:

Bearer Token

Include your API key in the Authorization header.

curl -X GET https://app.turtleapps.nl/api/projects \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Session Cookie

When using the API from the browser, session cookies from NextAuth.js are automatically included. This is the default authentication method for the TurtleApps web application.

API Keys

Generate API keys from your account settings. API keys are scoped to your tenant and inherit your user permissions.

⚠️ Keep your API keys secret. Never expose them in client-side code, public repositories, or browser requests. Rotate keys immediately if compromised.

Error Responses

Authentication failures return standard HTTP status codes:

// 401 Unauthorized — missing or invalid token
{
  "error": "Unauthorized",
  "message": "Invalid or expired authentication token"
}

// 403 Forbidden — valid token, insufficient permissions
{
  "error": "Forbidden",
  "message": "You do not have permission to access this resource"
}

NextAuth.js catch-all — handles sign-in, sign-out, callback, and session routes

NextAuth.js POST handler for credential/OAuth flows

Development-only login bypass (disabled in production)

List all projects for the current user/tenant

Create a new project

Get project details by ID

Update project settings

Delete a project

List project members

Add a member to the project

Remove a member from the project

List recent commits for the project repo

List deployments for the project

Get project analytics and metrics

Get aggregate quality score

Get quality summary breakdown

Get quality gate configuration

Update quality gate thresholds

Get approval workflow configuration

Update approval configuration

Get staging environment info

Get current workflow state

AI-generate tickets from a description

Get test results for the project

Get project theme/branding

Update project theme

Get client portal settings

Update client portal settings

Generate a deploy key for the repo

Test GitHub integration

Test Vercel integration

Get tickets overview/stats for a project

Create tickets from building blocks

List tickets (with filters: projectId, status, assignee)

Create a new ticket

Get ticket details

Update a ticket

Delete a ticket

Update ticket status

Update ticket priority

Accept a ticket for work

Submit ticket for review

Submit a code review

Approve a ticket

Reject a ticket with feedback

Merge ticket branch into main

Approve ticket for merge

Approve ticket for production deploy

Merge ticket branch to staging

Deploy ticket to staging environment

Withdraw ticket from staging

Rollback a deployed ticket

Create a Git branch for the ticket

List ticket comments

Add a comment to a ticket

List ticket version history

Get ticket progress details

Get preview deployment URL

Generate shareable preview link

Get ticket quality score

Run quality check on ticket

Run security scan on ticket code

AI-generate tests for the ticket

List approval status for a ticket

List ticket attachments

Upload an attachment

Delete an attachment

Get AI conversation history for ticket

Execute a quick command on the ticket

Evaluate quality gate for ticket

AI-analyze a ticket description

Analyze a screenshot to create a ticket

Bulk update tickets

Export tickets as CSV/JSON

List releases for a project

Create a new release

Get release details

Update release info

Deploy a release

Approve a release for deployment

Submit feedback on a release

Retry a failed merge in release

Merge tickets into this release

List all deployments

Create a deployment

Get deployment details

Trigger a new deployment

Rollback a deployment

List configured webhooks

Create a new webhook

Get webhook details

Update a webhook

Delete a webhook

Send a test webhook delivery

List webhook delivery history

GitHub webhook receiver (push, PR, status events)

Stripe webhook receiver (subscription and payment events)

Agent heartbeat / keep-alive

List tickets pending agent work

List stale tickets needing attention

List tickets pending agent review

Claim a ticket for processing

Mark ticket as started by agent

Report progress on a ticket

Mark ticket as completed by agent

Report agent failure on a ticket

Submit code diff for review

Claim a ticket for review

Submit agent review results

Get agent processing status

List releases pending agent merge

List releases pending production deploy

Report merge completion

Report deploy completion

Get deploy key for repo access

Get platform-wide statistics

Get platform analytics

List all users

Get user details

Update user (role, status)

Impersonate a user

List all tenants

Get tenant details

Update tenant settings

List recent platform errors

Force-reset a stuck release

List recent agent activities

Get user profile

Update user profile

List notifications for current user

Mark notification as read

Get notification preferences

Update notification preferences

List audit log entries

Access client portal via token

List marketplace add-ons

Install a marketplace add-on

Analyze a design file (Figma, image)

Create tickets from a design

Validate an invitation token

Submit onboarding data

Mark onboarding as complete

List epics

Create an epic

Get epic details

Update an epic

Get current tenant info

Get tenant details

Update tenant settings

List tenant invitations

Send a team invitation

Revoke an invitation

Get white-label settings

Update white-label settings

List users in current tenant

Get user details

Update user

Global search across projects and tickets

Create Stripe checkout session

Create Stripe billing portal session

Webhook Events

Configure webhooks to receive real-time notifications when events happen in your projects. Each webhook delivery includes an X-Webhook-Signature header for payload verification.

Verifying Webhook Signatures

import crypto from "crypto";

function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Rate Limiting

API requests are rate-limited per plan. Limits are applied per API key / session. When you exceed your rate limit, the API returns 429 Too Many Requests.

Plan	Requests	Burst	Webhooks	Note
Free	100 / hour	10 / sec	5	Best for personal projects
Pro	1,000 / hour	50 / sec	25	For growing teams
Business	10,000 / hour	200 / sec	100	For large organizations
Enterprise	Custom	Custom	Unlimited	Contact sales for custom limits

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1707400800
Retry-After: 3600  // Only present on 429 responses

429 Response

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 2025-02-08T13:00:00Z",
  "retryAfter": 3600
}

API Reference

Authentication

Webhooks

Rate Limits

Authentication

Bearer Token

Session Cookie

API Keys

Error Responses

Auth

Projects

Tickets

Releases

Deployments

Webhooks

Agent

Admin

Other

Webhook Events

Verifying Webhook Signatures

Rate Limiting

Rate Limit Headers

429 Response