Skip to content

Latest commit

 

History

History
648 lines (523 loc) · 10.5 KB

API_SPEC.md

File metadata and controls

648 lines (523 loc) · 10.5 KB

API Specification

Base URL: https://api.yourdomain.com (production) or http://localhost:3000 (dev)

Authentication

All authenticated endpoints require JWT in Authorization header:

Authorization: Bearer <jwt_token>

Response Format

Success Response

{
  "data": { ... },
  "message": "Success message (optional)"
}

Error Response

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

Endpoints

Authentication

POST /auth/register

Register a new user.

Request:

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response (201):

{
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  },
  "token": "jwt_token_here",
  "refreshToken": "refresh_token_here"
}

Errors:

  • 400: Validation error (invalid email, weak password)
  • 409: User already exists

POST /auth/login

Login existing user.

Request:

{
  "email": "user@example.com",
  "password": "securepassword123"
}

Response (200):

{
  "user": {
    "id": "uuid",
    "email": "user@example.com"
  },
  "token": "jwt_token_here",
  "refreshToken": "refresh_token_here"
}

Errors:

  • 401: Invalid credentials

GET /auth/me

Get current user info.

Headers: Authorization: Bearer <token>

Response (200):

{
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Errors:

  • 401: Invalid or expired token

POST /auth/refresh

Refresh access token using refresh token.

Request:

{
  "refreshToken": "refresh_token_here"
}

Response (200):

{
  "token": "new_jwt_token",
  "refreshToken": "new_refresh_token"
}

Errors:

  • 401: Invalid or expired refresh token

Folders

GET /folders

Get all folders for authenticated user.

Headers: Authorization: Bearer <token>

Response (200):

{
  "folders": [
    {
      "id": "uuid",
      "userId": "uuid",
      "name": "Work",
      "parentId": null,
      "isPinned": false,
      "position": 0,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "uuid",
      "userId": "uuid",
      "name": "Projects",
      "parentId": "uuid",
      "isPinned": false,
      "position": 0,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /folders

Create a new folder.

Headers: Authorization: Bearer <token>

Request:

{
  "name": "New Folder",
  "parentId": null,
  "isPinned": false
}

Response (201):

{
  "folder": {
    "id": "uuid",
    "userId": "uuid",
    "name": "New Folder",
    "parentId": null,
    "isPinned": false,
    "position": 0,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Errors:

  • 400: Validation error (missing name, invalid parentId)

GET /folders/:id

Get specific folder.

Headers: Authorization: Bearer <token>

Response (200):

{
  "folder": {
    "id": "uuid",
    "userId": "uuid",
    "name": "Folder Name",
    "parentId": null,
    "isPinned": false,
    "position": 0,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Errors:

  • 404: Folder not found or doesn't belong to user

PUT /folders/:id

Update folder.

Headers: Authorization: Bearer <token>

Request:

{
  "name": "Updated Name",
  "isPinned": true,
  "parentId": "uuid"
}

Response (200):

{
  "folder": {
    "id": "uuid",
    "userId": "uuid",
    "name": "Updated Name",
    "parentId": "uuid",
    "isPinned": true,
    "position": 0,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T01:00:00Z"
  }
}

Errors:

  • 404: Folder not found
  • 400: Invalid data (circular parent reference)

DELETE /folders/:id

Delete folder (and optionally its contents).

Headers: Authorization: Bearer <token>

Query Params:

  • cascade=true - Delete all subfolders and conversations (default: false)

Response (204): No content

Errors:

  • 404: Folder not found
  • 409: Folder has children (if cascade=false)

Prompts

GET /prompts

Get all prompts for authenticated user.

Headers: Authorization: Bearer <token>

Query Params:

  • category - Filter by category
  • favorite - Filter favorites only (true/false)
  • search - Search in title/content

Response (200):

{
  "prompts": [
    {
      "id": "uuid",
      "userId": "uuid",
      "title": "Explain Like I'm 5",
      "content": "Explain the following in simple terms: {{TEXT}}",
      "category": "Education",
      "isFavorite": false,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /prompts

Create new prompt.

Headers: Authorization: Bearer <token>

Request:

{
  "title": "Code Reviewer",
  "content": "Review this code and suggest improvements: {{CODE}}",
  "category": "Programming",
  "isFavorite": false
}

Response (201):

{
  "prompt": {
    "id": "uuid",
    "userId": "uuid",
    "title": "Code Reviewer",
    "content": "Review this code and suggest improvements: {{CODE}}",
    "category": "Programming",
    "isFavorite": false,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Errors:

  • 400: Validation error (missing title/content)

GET /prompts/:id

Get specific prompt.

Headers: Authorization: Bearer <token>

Response (200):

{
  "prompt": {
    "id": "uuid",
    "userId": "uuid",
    "title": "Code Reviewer",
    "content": "Review this code: {{CODE}}",
    "category": "Programming",
    "isFavorite": false,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Errors:

  • 404: Prompt not found

PUT /prompts/:id

Update prompt.

Headers: Authorization: Bearer <token>

Request:

{
  "title": "Updated Title",
  "content": "Updated content",
  "isFavorite": true
}

Response (200):

{
  "prompt": {
    "id": "uuid",
    "userId": "uuid",
    "title": "Updated Title",
    "content": "Updated content",
    "category": "Programming",
    "isFavorite": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T01:00:00Z"
  }
}

DELETE /prompts/:id

Delete prompt.

Headers: Authorization: Bearer <token>

Response (204): No content

Errors:

  • 404: Prompt not found

Chains

GET /chains

Get all chains for authenticated user.

Headers: Authorization: Bearer <token>

Response (200):

{
  "chains": [
    {
      "id": "uuid",
      "userId": "uuid",
      "name": "Blog Post Generator",
      "description": "Generates a complete blog post from a topic",
      "steps": [
        {
          "id": "uuid",
          "chainId": "uuid",
          "promptId": "uuid",
          "promptText": "Generate 5 blog post titles about: {{TOPIC}}",
          "position": 0,
          "outputVariable": "TITLES"
        },
        {
          "id": "uuid",
          "chainId": "uuid",
          "promptId": null,
          "promptText": "Write an outline for: {{TITLES[0]}}",
          "position": 1,
          "outputVariable": "OUTLINE"
        }
      ],
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

POST /chains

Create new chain.

Headers: Authorization: Bearer <token>

Request:

{
  "name": "Research Assistant",
  "description": "Helps research a topic",
  "steps": [
    {
      "promptText": "What are the key aspects of {{TOPIC}}?",
      "position": 0,
      "outputVariable": "ASPECTS"
    },
    {
      "promptText": "Explain {{ASPECTS}} in detail",
      "position": 1
    }
  ]
}

Response (201):

{
  "chain": {
    "id": "uuid",
    "userId": "uuid",
    "name": "Research Assistant",
    "description": "Helps research a topic",
    "steps": [...],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

GET /chains/:id

Get specific chain.

Headers: Authorization: Bearer <token>

Response (200):

{
  "chain": {
    "id": "uuid",
    "name": "Chain Name",
    "description": "Description",
    "steps": [...],
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}

Errors:

  • 404: Chain not found

PUT /chains/:id

Update chain.

Headers: Authorization: Bearer <token>

Request:

{
  "name": "Updated Name",
  "description": "Updated description",
  "steps": [...]
}

Response (200):

{
  "chain": {
    "id": "uuid",
    "name": "Updated Name",
    "steps": [...],
    "updatedAt": "2024-01-01T01:00:00Z"
  }
}

DELETE /chains/:id

Delete chain.

Headers: Authorization: Bearer <token>

Response (204): No content


Sync

GET /sync/pull

Pull all user data (full sync).

Headers: Authorization: Bearer <token>

Query Params:

  • since - ISO timestamp, only return items updated since this time

Response (200):

{
  "data": {
    "folders": [...],
    "prompts": [...],
    "chains": [...],
    "conversations": [...],
    "bookmarks": [...]
  },
  "timestamp": "2024-01-01T00:00:00Z"
}

POST /sync/push

Push local changes to server.

Headers: Authorization: Bearer <token>

Request:

{
  "folders": [...],
  "prompts": [...],
  "chains": [...],
  "lastSyncTimestamp": "2024-01-01T00:00:00Z"
}

Response (200):

{
  "success": true,
  "conflicts": [],
  "timestamp": "2024-01-01T01:00:00Z"
}

Common HTTP Status Codes

  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 204 No Content - Request succeeded with no response body
  • 400 Bad Request - Invalid request data
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource conflict (e.g., duplicate)
  • 500 Internal Server Error - Server error

Rate Limiting

  • Limit: 100 requests per minute per user
  • Headers:
    • X-RateLimit-Limit: Maximum requests allowed
    • X-RateLimit-Remaining: Remaining requests
    • X-RateLimit-Reset: Time when limit resets (Unix timestamp)

Versioning

API version is included in the base URL: /v1/

Example: https://api.yourdomain.com/v1/folders