API reference
REST endpoints, authentication, response shapes, pagination, errors, and CORS.
Base URL
Use the Convex site URL shown in the dashboard Publishing card:
https://<deployment>.convex.siteAll paths below are relative to this base URL.
Authentication
Every request requires a bearer API key:
Authorization: Bearer ink_live_...Missing, malformed, revoked, or unknown keys return HTTP 401:
{ "error": "invalid_api_key" }GET /api/v1/site
Returns the connected site:
{
"name": "Example",
"url": "https://example.com"
}TypeScript type:
type Site = {
name: string;
url: string;
};GET /api/v1/articles
Returns published article summaries. Query parameters:
| Parameter | Type | Description |
|---|---|---|
limit | number | Optional page size. |
cursor | string | Optional cursor returned by the previous page. |
Response:
type ArticleSummary = {
slug: string;
title: string;
description: string;
publishedAt: string;
updatedAt: string;
coverImage: {
url: string;
alt: string;
width: number;
height: number;
} | null;
keyword: string;
};
type ListArticlesResponse = {
articles: ArticleSummary[];
nextCursor: string | null;
};When nextCursor is not null, pass it as the next request's cursor parameter. The SDK's allArticles() method follows these pages until nextCursor is null.
GET /api/v1/articles/<slug>
Returns one complete published article:
type Article = ArticleSummary & {
intent: string;
markdown: string;
html: string;
sources: { url: string; title: string }[];
internalLinks: { url: string; anchor: string }[];
};If the slug does not exist or is not published, the response is HTTP 404:
{ "error": "not_found" }Response headers
The API sends:
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type
Content-Type: application/json
Cache-Control: no-storeOPTIONS requests receive the CORS headers without an article response. The API is intended for server-side pulls, so keep the API key out of browser bundles even though the endpoint permits cross-origin reads.