Skip to main content

API Documentation v1

Welcome to the Placio API v1 documentation. This version provides comprehensive access to all Placio platform features.

Base URL​

All API endpoints are prefixed with /v1. The actual backend path is /v1/..., but for documentation purposes, we also reference the desired format /v1/....

Example:

  • Actual backend path: POST /v1/workspace/:workspaceId/sessions
  • Desired format: POST /v1/workspace/:workspaceId/sessions
note

The API currently uses /v1 prefix. Future versions may use /api/v1 prefix. Always check the actual endpoint path in the documentation.

Authentication​

Most endpoints require authentication. The API supports:

  • JWT Token Authentication: Include Authorization: Bearer <token> header
  • Cookie-based Authentication: Some endpoints use HTTP-only cookies for authentication

See the Authentication endpoints for details on obtaining tokens.

Versioning Policy​

Versioning Rules​

Minor Additive Changes (Stay in v1):

  • Adding new optional fields to request/response
  • Adding new optional query parameters
  • Adding new endpoints
  • Adding new enum values (backward compatible)
  • Adding new optional headers

Breaking Changes (Require v2):

  • Removing fields from request/response
  • Changing field types or meanings
  • Making optional fields required
  • Changing required fields to optional (may break clients expecting them)
  • Removing endpoints
  • Changing HTTP methods
  • Changing response structure significantly
  • Removing enum values

Deprecation Policy​

When an endpoint is deprecated:

  1. Deprecation Notice: The endpoint will be marked with a :::caution Deprecated block
  2. Removal Date: A specific removal date will be provided
  3. Replacement Endpoint: A link to the replacement endpoint in v2 will be included
  4. Migration Period: At least 6 months notice before removal
Deprecated

This endpoint will be removed on [DATE]. Please migrate to [v2 endpoint link].

Common Response Codes​

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request body or query parameters
  • 401 Unauthorized: Missing or invalid authentication token
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict (e.g., duplicate entry)
  • 422 Unprocessable Entity: Validation errors
  • 500 Internal Server Error: Server error

Rate Limiting​

Rate limiting may be applied to prevent abuse. Check response headers for rate limit information.

Error Response Format​

All errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Getting Started​

  1. Authenticate: Start with Admin Authentication or see the Authentication endpoints for details
  2. Explore Endpoints: Browse endpoints by domain in the sidebar
  3. Check Examples: Each endpoint includes request/response examples

Endpoint Domains​

Workspace Resources​

All workspace-scoped endpoints are organized under Workspace Resources:

Public Endpoints​

Platform Endpoints​