Back to Home
API REFERENCE

API Reference

Complete API documentation for integrating with Covalynce

Authentication

All API requests require authentication via Bearer token. Get your API key from the dashboard settings.

curl https://api.covalynce.com/v1/generations \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"

API keys are scoped to your account and can be regenerated at any time. Keep them secure and never commit them to version control.

Base URL

https://api.covalynce.com/v1

Endpoints

POST/generations

Create a new content generation request.

{
"source":
"github",
"event":
"pr.merged",
"repo":
"your-org/your-repo",
"pr_number":
123,
"channels":
["twitter", "linkedin"],
"template":
"feature-release" // optional
}
Response:
{
"id":
"gen_abc123",
"status":
"pending",
"created_at":
"2024-01-15T10:30:00Z"
}
GET/generations

List all generations with optional filters.

GET /generations?status=pending&limit=10&offset=0

Query parameters: status, limit, offset, repo

GET/generations/:id

Retrieve a specific generation by ID.

Response:
{
"id":
"gen_abc123",
"status":
"completed",
"content":
{
"twitter":
"🚀 New feature is live! ...",
"linkedin":
"We're excited to announce...",
}
}
PUT/generations/:id/approve

Approve and publish a generated content draft.

{
"channels":
["twitter", "linkedin"] // optional, defaults to all
}
DELETE/generations/:id

Delete a generation draft.

GET/integrations

List all connected integrations.

POST/integrations/:name/connect

Initiate OAuth flow for an integration.

Webhooks

Receive real-time notifications when content is generated. Configure webhook endpoints in your dashboard or via API.

Creating a Webhook

POST /webhooks
{
"url":
"https://your-app.com/webhooks/covalynce",
"events":
["generation.completed", "generation.approved"],
"secret":
"your-webhook-secret"
}

Webhook Payload

{
"event":
"generation.completed",
"generation_id":
"gen_abc123",
"status":
"pending_approval",
"content":
{ ... }
"timestamp":
"2024-01-15T10:30:00Z",
"signature":
"sha256=..."
}

Webhook signatures use HMAC SHA-256. Verify signatures using your webhook secret to ensure requests are from Covalynce.

Error Handling

All errors follow a consistent format:

{
"error":
{
"code":
"RATE_LIMIT_EXCEEDED",
"message":
"Rate limit exceeded. Try again in 60 seconds.",
"status":
429
}
}
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
429 - Rate Limit Exceeded
500 - Internal Server Error

Rate Limits

Free Plan
10 requests/minute
Starter Plan
60 requests/minute
Pro Plan
Unlimited

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

SDKs & Libraries

JavaScript/TypeScript

npm install @covalynce/sdk

Python

pip install covalynce-sdk

Go

go get github.com/covalynce/go-sdk

Official SDKs handle authentication, retries, and error handling automatically. See documentation for examples.