API Documentation

Programmatic access to your CodeVault snippets.

Sign up for access

Introduction

The CodeVault REST API lets you read, create, update, and delete snippets programmatically. All responses are JSON. All requests that modify data require authentication via an API key.

Base URL: 

https://codevault-production-86f2.up.railway.app/api/v1

Authentication

Authenticate by including your API key in the Authorization header of every request. You can generate or regenerate your API key from your Settings page.

Header format

Authorization: Bearer YOUR_API_KEY

Example with curl

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://codevault-production-86f2.up.railway.app/api/v1/snippets

Rate Limits

The API is rate limited to 100 requests per hour per API key. When the limit is exceeded, the API returns HTTP 429 Too Many Requests.

429 response 
{
  "error": "Rate limit exceeded. Max 100 requests per hour."
}

Endpoints

GET /api/v1/snippets List your snippets
GET /api/v1/snippets/{id} Get a single snippet
POST /api/v1/snippets Create a snippet
PUT /api/v1/snippets/{id} Update a snippet
DELETE /api/v1/snippets/{id} Delete a snippet
GET /api/v1/snippets

Returns a paginated list of snippets belonging to the authenticated user.

Request headers

Authorization: Bearer YOUR_API_KEY

Query parameters

Optional parameters
page      integer   Page number (default: 1)
limit     integer   Results per page, max 100 (default: 20)
language  string    Filter by programming language
tag       string    Filter by tag

Example response

200 OK
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Debounce function",
      "description": "Limits how often a function can fire.",
      "language": "javascript",
      "tags": "utils,performance",
      "is_public": true,
      "view_count": 42,
      "star_count": 7,
      "created_at": "2026-03-10T14:22:00Z",
      "updated_at": "2026-03-10T14:22:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
GET /api/v1/snippets/{id}

Returns a single snippet by ID. You can only retrieve snippets you own, or public snippets.

Request headers

Authorization: Bearer YOUR_API_KEY

Example response

200 OK
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Debounce function",
  "description": "Limits how often a function can fire.",
  "code": "function debounce(fn, delay) {\n  let t;\n  return (...args) => {\n    clearTimeout(t);\n    t = setTimeout(() => fn(...args), delay);\n  };\n}",
  "language": "javascript",
  "tags": "utils,performance",
  "is_public": true,
  "view_count": 42,
  "star_count": 7,
  "created_at": "2026-03-10T14:22:00Z",
  "updated_at": "2026-03-10T14:22:00Z"
}

Error response

404 Not Found
{ "error": "Snippet not found" }
POST /api/v1/snippets

Creates a new snippet owned by the authenticated user.

Request headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body

JSON body
{
  "title":       "string  (required, max 255 chars)",
  "code":        "string  (required)",
  "language":    "string  (required, e.g. javascript)",
  "description": "string  (optional)",
  "tags":        "string  (optional, comma-separated)",
  "is_public":   "boolean (optional, default false)"
}

Example response

201 Created
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "title": "My new snippet",
  "language": "python",
  "created_at": "2026-03-17T09:00:00Z"
}

Error response

422 Unprocessable Entity
{ "error": "title and code are required" }
PUT /api/v1/snippets/{id}

Updates an existing snippet. You may only update snippets you own. Send only the fields you want to change.

Request headers

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body

JSON body (all fields optional)
{
  "title":       "string",
  "code":        "string",
  "language":    "string",
  "description": "string",
  "tags":        "string",
  "is_public":   "boolean"
}

Example response

200 OK
{ "success": true, "id": "550e8400-e29b-41d4-a716-446655440000" }
DELETE /api/v1/snippets/{id}

Permanently deletes a snippet and all associated stars. You may only delete snippets you own.

Request headers

Authorization: Bearer YOUR_API_KEY

Example response

200 OK
{ "success": true }

Error response

403 Forbidden
{ "error": "Forbidden" }