API Reference

Complete reference for the DrBeat Profiles API. Use these endpoints to integrate doctor profile enrichment into your workflows.

Introduction

The DrBeat Profiles API provides a RESTful interface for managing doctor profile enrichment jobs. All endpoints return JSON and use standard HTTP methods.

Base URL

/api

Content-Type

application/json

Encoding

UTF-8

Endpoints

POST
/api/jobs

Create a new enrichment job for processing doctor profiles.

Request Body

{
  "total": 10,
  "status": "PENDING"
}

Response Example

{
  "id": "cl...",
  "status": "PENDING",
  "total": 10,
  "processed": 0,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
GET
/api/jobs

List all jobs with their profile counts.

Response Example

[
  {
    "id": "cl...",
    "status": "COMPLETED",
    "total": 10,
    "processed": 10,
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:00Z",
    "_count": {
      "profiles": 10
    }
  }
]
GET
/api/jobs/[id]

Get a specific job with its profiles.

Response Example

{
  "id": "cl...",
  "status": "COMPLETED",
  "total": 10,
  "processed": 10,
  "createdAt": "2024-01-15T10:30:00Z",
  "profiles": [...]
}
PUT
/api/jobs/[id]

Update job progress, status, or add notes.

Request Body

{
  "status": "RUNNING",
  "processed": 5
}

Response Example

{
  "id": "cl...",
  "status": "RUNNING",
  "total": 10,
  "processed": 5,
  "updatedAt": "2024-01-15T10:32:00Z"
}
GET
/api/profiles

List profiles with optional filters.

Query Parameters

ParameterDescription
jobIdFilter by job ID
searchSearch in name, specialty, city
specialtyFilter by specialty
cityFilter by city
confidenceFilter by confidence (HIGH/MEDIUM/LOW)
statusFilter by status

Response Example

{
  "profiles": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}
POST
/api/profiles

Create or update a profile with enriched data.

Request Body

{
  "jobId": "cl...",
  "fullName": "Dr. Jane Smith",
  "specialty": "Cardiology",
  "city": "Athens",
  "confidence": "HIGH",
  "status": "COMPLETED",
  "aiSummary": "Experienced cardiologist...",
  "highlights": ["15+ years experience", "Specializes in interventional cardiology"]
}

Response Example

{
  "id": "cl...",
  "jobId": "cl...",
  "fullName": "Dr. Jane Smith",
  "specialty": "Cardiology",
  "confidence": "HIGH",
  "status": "COMPLETED",
  "createdAt": "2024-01-15T10:30:00Z"
}
GET
/api/profiles/[id]

Get a single profile with all details.

Response Example

{
  "id": "cl...",
  "fullName": "Dr. Jane Smith",
  "titles": "MD, PhD",
  "specialty": "Cardiology",
  "city": "Athens",
  "rating": 4.8,
  "reviewCount": 127,
  "confidence": "HIGH",
  "status": "COMPLETED",
  "aiSummary": "Experienced cardiologist...",
  "highlights": [...],
  "education": [...],
  "certifications": [...]
}

⚡OpenClaw Integration Notes

Workflow

  1. Create a job using POST /api/jobs
  2. Update job status to RUNNING when starting enrichment
  3. For each doctor profile found, create/update using POST /api/profiles
  4. Update processed count as you progress
  5. Set job status to COMPLETED or FAILED when done

Error Handling

The API returns standard HTTP status codes:

  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request data
  • 404 Not Found - Resource not found
  • 500 Server Error - Internal server error

Rate Limiting

The API implements rate limiting to ensure fair usage. Current limits:

  • 100 requests per minute per IP
  • 1000 requests per hour per IP

When rate limited, the API returns a 429 Too Many Requests status with a Retry-After header.

Example OpenClaw Workflow

// 1. Create a job
const job = await fetch('/api/jobs', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ total: 10, status: 'PENDING' })
}).then(r => r.json());

// 2. Start processing
await fetch(`/api/jobs/${job.id}`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'RUNNING' })
});

// 3. Add profiles as you find them
await fetch('/api/profiles', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jobId: job.id,
    fullName: 'Dr. Example',
    specialty: 'Cardiology',
    confidence: 'HIGH',
    status: 'COMPLETED'
  })
});

// 4. Complete the job
await fetch(`/api/jobs/${job.id}`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'COMPLETED' })
});