rest_api_reference - fleXRPL/contractAI GitHub Wiki
Complete reference for ContractAI REST API endpoints, authentication, and usage
This document provides a comprehensive reference for the ContractAI REST API, including endpoints, authentication, request/response formats, and usage examples.
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]
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
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]
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]
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}]
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]
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
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]
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
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]
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
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]
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]
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
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]
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]
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/>}
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/>}
Need help with the API? Contact our API team at [email protected] or visit our API Portal
- Review API documentation
- Set up authentication
- Test endpoints
- Implement SDK
- Configure webhooks
- Monitor usage