API Documentation

Complete API reference with examples and best practices for integrating with Peregrine

REST API Reference

Base URL

https://api.peregrinetec.com/v1

Common Endpoints

GET/patients/{id}

Retrieve patient information by ID

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.peregrinetec.com/v1/patients/12345

POST/ai/agents/execute

Execute an AI agent task

curl -X POST -H "Content-Type: application/json" \
  -d '{"agent": "intake-processor", "data": {...}}' \
  https://api.peregrinetec.com/v1/ai/agents/execute

PUT/patients/{id}/records

Update patient records

DELETE/datasets/{id}

Delete a synthetic dataset

Response Format

All API responses follow a consistent JSON structure:

{
  "success": true,
  "data": {
    // Response data here
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0"
  }
}

GraphQL Schema

Peregrine provides a GraphQL API for flexible data queries and mutations.

GraphQL Endpoint

https://api.peregrinetec.com/graphql

Example Query

query GetPatientData($patientId: ID!) {
  patient(id: $patientId) {
    id
    name
    dateOfBirth
    conditions {
      code
      description
      onsetDate
    }
    medications {
      name
      dosage
      frequency
    }
  }
}

Example Mutation

mutation CreateAIAgent($input: CreateAgentInput!) {
  createAgent(input: $input) {
    id
    name
    status
    capabilities
  }
}

Authentication & Authorization

OAuth 2.0 Flow

Peregrine uses OAuth 2.0 with AWS Cognito for secure authentication.

1
Request Authorization
Direct users to the authorization endpoint
2
Exchange Code for Token
Trade authorization code for access token
3
Use Access Token
Include token in API request headers

API Keys

For server-to-server communication, use API keys with proper scoping.

Security Best Practice

Always store API keys in environment variables or secure key management systems. Never commit keys to version control.

Rate Limiting & Quotas

Rate Limits by Tier

Tier	Requests/Min
Starter	100
Enterprise	1,000
GovCloud	Custom

Response Headers

X-RateLimit-Limit: 1000

X-RateLimit-Remaining: 999

X-RateLimit-Reset: 1640995200

Rate Limit Exceeded

When rate limits are exceeded, the API returns a 429 status code with a Retry-After header indicating when to retry the request.