API Endpoints

Complete reference for all available API endpoints, parameters, and response formats.

Overview

The Sapphire Legal AI API provides RESTful endpoints for managing cases, documents, users, and system configurations. All endpoints return JSON responses and use standard HTTP status codes.

Base URL

All API requests should be made to:

https://api.sapphirelegal.ai/api/v1

Rate limits

API requests are subject to rate limiting to ensure fair usage and system stability:

Authenticated users: 1000 requests per hour
API keys: 5000 requests per hour
Admin endpoints: 100 requests per hour

Core endpoints

Authentication

Method	Endpoint	Description
POST	`/auth/login`	User login and JWT token generation
POST	`/auth/refresh`	Refresh expired JWT token
POST	`/auth/logout`	Invalidate JWT token

Cases

Method	Endpoint	Description
GET	`/cases`	List all cases (with pagination)
POST	`/cases`	Create a new case
GET	`/cases/{id}`	Get case details by ID
PUT	`/cases/{id}`	Update case information
DELETE	`/cases/{id}`	Delete a case

Documents

Method	Endpoint	Description
GET	`/cases/{case_id}/documents`	List documents in a case
POST	`/cases/{case_id}/documents`	Upload a new document
GET	`/documents/{id}`	Get document metadata
GET	`/documents/{id}/content`	Download document content
DELETE	`/documents/{id}`	Delete a document

Request examples

Creating a new case

POST /api/v1/cases
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

{
  "title": "Smith v. Johnson",
  "case_number": "CV-2025-001",
  "case_type": "litigation",
  "jurisdiction": "federal",
  "client_name": "John Smith",
  "description": "Contract dispute regarding software licensing agreement",
  "status": "active",
  "priority": "high"
}

Uploading a document

POST /api/v1/cases/123/documents
Authorization: Bearer <your_jwt_token>
Content-Type: multipart/form-data

{
  "file": <file_data>,
  "title": "Complaint",
  "document_type": "pleading",
  "tags": ["complaint", "initial_filing"],
  "description": "Initial complaint filed with the court"
}

Searching cases

GET /api/v1/cases?search=contract&status=active&case_type=litigation&page=1&limit=20
Authorization: Bearer <your_jwt_token>
Content-Type: application/json

Response formats

Successful response

{
  "success": true,
  "data": {
    "id": "case_1234567890abcdef",
    "title": "Smith v. Johnson",
    "case_number": "CV-2025-001",
    "case_type": "litigation",
    "jurisdiction": "federal",
    "client_name": "John Smith",
    "description": "Contract dispute regarding software licensing agreement",
    "status": "active",
    "priority": "high",
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  },
  "meta": {
    "request_id": "req_1234567890abcdef",
    "timestamp": "2025-01-20T10:30:00Z"
  }
}

Error response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "title",
        "message": "Title is required"
      },
      {
        "field": "case_number",
        "message": "Case number must be unique"
      }
    ]
  },
  "meta": {
    "request_id": "req_1234567890abcdef",
    "timestamp": "2025-01-20T10:30:00Z"
  }
}

Paginated response

{
  "success": true,
  "data": [
    // Array of case objects
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8
    },
    "request_id": "req_1234567890abcdef",
    "timestamp": "2025-01-20T10:30:00Z"
  }
}

Query parameters

Common parameters

Parameter	Type	Description	Example
`page`	integer	Page number for pagination	1
`limit`	integer	Number of items per page	20
`search`	string	Search query for text fields	contract
`sort`	string	Sort field	created_at
`order`	string	Sort order (asc/desc)	desc

Tip

Pro tip: Use the fields parameter to request only the data you need, improving performance and reducing bandwidth.

What's next

Webhooks - Set up event-driven notifications
SDKs & Libraries - Use official client libraries
System Configuration - Customize API behavior