rest_api_reference

ContractAI REST API Reference

Complete reference for ContractAI REST API endpoints, authentication, and usage

Overview

This document provides a comprehensive reference for the ContractAI REST API, including endpoints, authentication, request/response formats, and usage examples.

API Architecture

graph TD
    A[API Gateway] --> B[Authentication]
    A --> C[Rate Limiting]
    A --> D[Request Router]

    B --> B1[OAuth 2.0]
    B --> B2[JWT]
    B --> B3[API Keys]

    C --> C1[Quotas]
    C --> C2[Throttling]
    C --> C3[Monitoring]

    D --> D1[Agent API]
    D --> D2[Knowledge API]
    D --> D3[System API]

Loading

Authentication

Authentication Flow

sequenceDiagram
    participant Client
    participant Auth as Auth Server
    participant API as API Gateway
    participant Service as Service

    Client->>Auth: Request Token
    Auth->>Client: Access Token
    Client->>API: API Request + Token
    API->>Auth: Validate Token
    Auth->>API: Token Valid
    API->>Service: Process Request
    Service->>API: Response
    API->>Client: API Response

Loading

Token Types

graph TD
    A[Tokens] --> B[Access Token]
    A --> C[Refresh Token]
    A --> D[API Key]

    B --> B1[Short-lived]
    B --> B2[JWT]
    B --> B3[Scoped]

    C --> C1[Long-lived]
    C --> C2[Secure]
    C --> C3[Revocable]

    D --> D1[Service]
    D --> D2[Client]
    D --> D3[Admin]

Loading

API Endpoints

Agent Management

graph TD
    A[Agent API] --> B[Creation]
    A --> C[Management]
    A --> D[Monitoring]

    B --> B1[POST /agents]
    B --> B2[POST /agents/template]
    B --> B3[POST /agents/bulk]

    C --> C1[GET /agents]
    C --> C2[PUT /agents/{id}]
    C --> C3[DELETE /agents/{id}]

    D --> D1[GET /agents/{id}/status]
    D --> D2[GET /agents/{id}/metrics]
    D --> D3[GET /agents/{id}/logs]

Loading

Knowledge Base

graph TD
    A[Knowledge API] --> B[Documents]
    A --> C[Search]
    A --> D[Management]

    B --> B1[POST /knowledge/documents]
    B --> B2[GET /knowledge/documents/{id}]
    B --> B3[PUT /knowledge/documents/{id}]

    C --> C1[GET /knowledge/search]
    C --> C2[POST /knowledge/query]
    C --> C3[GET /knowledge/suggestions]

    D --> D1[GET /knowledge/categories]
    D --> D2[PUT /knowledge/tags]
    D --> D3[DELETE /knowledge/documents/{id}]

Loading

System Management

graph TD
    A[System API] --> B[Health]
    A --> C[Configuration]
    A --> D[Monitoring]

    B --> B1[GET /health]
    B --> B2[GET /health/detailed]
    B --> B3[GET /health/history]

    C --> C1[GET /config]
    C --> C2[PUT /config]
    C --> C3[GET /config/schema]

    D --> D1[GET /metrics]
    D --> D2[GET /logs]
    D --> D3[GET /alerts]

Loading

Request/Response Patterns

Standard Request Flow

sequenceDiagram
    participant Client
    participant Gateway as API Gateway
    participant Service as Service
    participant DB as Database

    Client->>Gateway: HTTP Request
    Gateway->>Gateway: Validate
    Gateway->>Gateway: Rate Limit
    Gateway->>Service: Route Request
    Service->>DB: Query/Update
    DB->>Service: Result
    Service->>Gateway: Response
    Gateway->>Client: HTTP Response

Loading

Error Handling

graph TD
    A[Errors] --> B[4xx]
    A --> C[5xx]
    A --> D[Business]

    B --> B1[400 Bad Request]
    B --> B2[401 Unauthorized]
    B --> B3[403 Forbidden]

    C --> C1[500 Server Error]
    C --> C2[502 Bad Gateway]
    C --> C3[503 Service Unavailable]

    D --> D1[Validation]
    D --> D2[Business Rules]
    D --> D3[Rate Limits]

Loading

Rate Limiting

Rate Limit Flow

sequenceDiagram
    participant Client
    participant Gateway as API Gateway
    participant Redis as Redis
    participant Service as Service

    Client->>Gateway: Request
    Gateway->>Redis: Check Limit
    alt Under Limit
        Redis->>Gateway: Allow
        Gateway->>Service: Process
        Service->>Gateway: Response
        Gateway->>Client: Success
    else Over Limit
        Redis->>Gateway: Block
        Gateway->>Client: 429 Too Many Requests
    end

Loading

Rate Limit Tiers

graph TD
    A[Tiers] --> B[Free]
    A --> C[Standard]
    A --> D[Enterprise]

    B --> B1[1000 req/day]
    B --> B2[10 req/min]
    B --> B3[Basic Features]

    C --> C1[10000 req/day]
    C --> C2[100 req/min]
    C --> C3[Advanced Features]

    D --> D1[Unlimited]
    D --> D2[Custom Limits]
    D --> D3[All Features]

Loading

Webhooks

Webhook Flow

sequenceDiagram
    participant Service as Service
    participant Queue as Queue
    participant Webhook as Webhook
    participant Client as Client

    Service->>Queue: Event
    Queue->>Webhook: Process
    Webhook->>Client: POST Request
    alt Success
        Client->>Webhook: 200 OK
        Webhook->>Queue: Acknowledge
    else Failure
        Client->>Webhook: Error
        Webhook->>Queue: Retry
    end

Loading

Webhook Events

graph TD
    A[Events] --> B[Agent]
    A --> C[Knowledge]
    A --> D[System]

    B --> B1[agent.created]
    B --> B2[agent.updated]
    B --> B3[agent.deleted]

    C --> C1[document.added]
    C --> C2[document.updated]
    C --> C3[document.deleted]

    D --> D1[system.alert]
    D --> D2[system.maintenance]
    D --> D3[system.update]

Loading

SDK Integration

SDK Architecture

graph TD
    A[SDK] --> B[Client]
    A --> C[Models]
    A --> D[Utils]

    B --> B1[REST Client]
    B --> B2[WebSocket]
    B --> B3[Streaming]

    C --> C1[Data Models]
    C --> C2[Request/Response]
    C --> C3[Validation]

    D --> D1[Auth]
    D --> D2[Retry]
    D --> D3[Logging]

Loading

Integration Flow

sequenceDiagram
    participant App as Application
    participant SDK as SDK
    participant API as API
    participant Service as Service

    App->>SDK: Initialize
    SDK->>API: Authenticate
    API->>SDK: Token
    App->>SDK: API Call
    SDK->>API: Request
    API->>Service: Process
    Service->>API: Response
    API->>SDK: Result
    SDK->>App: Data

Loading

Best Practices

API Usage

graph TD
    A[Best Practices] --> B[Performance]
    A --> C[Security]
    A --> D[Reliability]

    B --> B1[Caching]
    B --> B2[Pagination]
    B --> B3[Compression]

    C --> C1[HTTPS]
    C --> C2[Token Management]
    C --> C3[Input Validation]

    D --> D1[Retry Logic]
    D --> D2[Error Handling]
    D --> D3[Monitoring]

Loading

Security Guidelines

graph TD
    A[Security] --> B[Authentication]
    A --> C[Authorization]
    A --> D[Data Protection]

    B --> B1[Token Security]
    B --> B2[Credential Management]
    B --> B3[Session Handling]

    C --> C1[Role-Based Access]
    C --> C2[Resource Scoping]
    C --> C3[Permission Checks]

    D --> D1[Encryption]
    D --> D2[Data Validation]
    D --> D3[Audit Logging]

Loading

Examples

Agent Creation

sequenceDiagram
    participant Client
    participant API as API
    participant Service as Service
    participant DB as Database

    Client->>API: POST /agents
    Note over Client,API: {<br/>name: "ContractAgent",<br/>type: "legal",<br/>config: {...}<br/>}
    API->>Service: Create Agent
    Service->>DB: Store
    DB->>Service: Created
    Service->>API: Agent ID
    API->>Client: 201 Created
    Note over Client,API: {<br/>id: "agent_123",<br/>status: "initializing"<br/>}

Loading

Document Search

sequenceDiagram
    participant Client
    participant API as API
    participant Service as Service
    participant DB as Database

    Client->>API: GET /knowledge/search
    Note over Client,API: ?q=contract&type=legal
    API->>Service: Search
    Service->>DB: Query
    DB->>Service: Results
    Service->>API: Documents
    API->>Client: 200 OK
    Note over Client,API: {<br/>results: [...],<br/>total: 42,<br/>page: 1<br/>}

Loading

---

Need help with the API? Contact our API team at api@contractai.com or visit our API Portal

Next Steps

1. Review API documentation
2. Set up authentication
3. Test endpoints
4. Implement SDK
5. Configure webhooks
6. Monitor usage

Additional Resources

• API Documentation
• SDK Guide
• Webhook Guide
• Security Guide
• API Portal