API Reference

The Recoger API allows you to integrate device compliance and service tracking into your workflows, automate reporting, and build custom integrations.

Base URL

https://api.recoger.app/v1

Authentication

All API requests require authentication using a Bearer token. You can use either:

• Access Token — Short-lived JWT from the login flow
• API Key — Long-lived key for server-to-server integrations

Using an Access Token

curl -X GET https://api.recoger.app/v1/devices \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Using an API Key

Generate API keys in Settings → API Keys. API keys have the prefix rk_.

curl -X GET https://api.recoger.app/v1/devices \
  -H "Authorization: Bearer rk_live_..."

Rate Limits

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1704412800

Endpoints

Authentication

POST /auth/login

Authenticate and receive access tokens.

{
  "username": "user@example.com",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "user_id": "user_abc123",
  "tenant_id": "tenant_xyz789",
  "role": "admin"
}

POST /auth/refresh

Refresh an expired access token.

{
  "refresh_token": "eyJhbGciOiJSUzI1NiIs..."
}

POST /auth/logout

Invalidate the current access token.

Devices

GET /devices/my-devices

List devices owned by the current user.

Query parameters:

• include_data — Include device data (default: true)
• skip — Pagination offset (default: 0)
• limit — Results per page (default: 50, max: 100)

GET /devices/tenant-devices

List all devices in the tenant. Admin only.

Query parameters:

• user_id — Filter by user
• include_data — Include device data (default: true)
• skip / limit — Pagination

GET /devices/{device_id}

Get details for a specific device.

Response:

{
  "id": "dev_abc123",
  "device_name": "MacBook Pro 16\"",
  "serial_number": "C02XL0GTJG5J",
  "device_type": "laptop",
  "os_type": "macos",
  "os_version": "14.2.1",
  "last_seen": "2026-01-04T10:30:00Z",
  "user_id": "user_xyz",
  "device_data": [...]
}

POST /devices/report

Report device data from an agent. Creates or updates the device.

{
  "device_name": "MacBook Pro 16\"",
  "serial_number": "C02XL0GTJG5J",
  "device_type": "laptop",
  "os_type": "macos",
  "os_version": "14.2.1",
  "security": {
    "disk_encryption": true,
    "firewall_enabled": true,
    "screen_lock_enabled": true
  },
  "hardware": {...},
  "software": {...}
}

GET /devices/{device_id}/data/{data_type}

Get device data by type (security, hardware, software, network, custom).

Services

GET /services

List services. Admins see all; users see services they own.

Query parameters:

• status — Filter by status
• search — Search by name
• skip / limit — Pagination

POST /services

Create a new service. Admin only.

{
  "name": "GitHub",
  "description": "Source code hosting",
  "category": "development",
  "url": "https://github.com",
  "owner_id": "user_xyz",
  "data_classification": "confidential",
  "sso_enabled": true,
  "mfa_enforced": true
}

GET /services/{service_id}

Get service details.

PATCH /services/{service_id}

Update a service. Admin or service owner.

DELETE /services/{service_id}

Delete a service. Admin only.

GET /services/my-dashboard

Get dashboard stats for services owned by current user.

Security Reviews

GET /services/{service_id}/reviews

List reviews for a service.

POST /services/{service_id}/reviews

Create a security review.

{
  "review_date": "2026-01-04",
  "next_review_date": "2026-04-04",
  "findings": "All security controls verified.",
  "sso_enabled": true,
  "mfa_enforced": true,
  "audit_logging_enabled": true
}

Users

GET /users/me

Get current user profile.

PATCH /users/me

Update current user profile.

GET /users (Admin)

List users in tenant.

Reports

POST /reports/compliance

Generate a compliance report.

{
  "framework": "iso27001",
  "format": "pdf",
  "date_range": {
    "start": "2025-01-01",
    "end": "2026-01-01"
  }
}

GET /reports/{report_id}

Get a generated report.

GET /reports

List generated reports.

Audit Logs

GET /audit-logs

List audit log entries. Admin only.

Query parameters:

• event_name — Filter by event type
• resource_type — Filter by resource (device, service, user)
• actor_id — Filter by actor
• start_date / end_date — Date range

Error Handling

Errors return appropriate HTTP status codes with a JSON body:

{
  "detail": "Device not found"
}

OpenAPI Specification

The full OpenAPI spec is available at:

https://api.recoger.app/openapi.json

Interactive documentation is available at:

https://api.recoger.app/docs

SDKs & Libraries

Official SDKs are coming soon. In the meantime, the API works with any HTTP client.

Example using Python:

import requests

api_key = "rk_live_..."
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.get(
    "https://api.recoger.app/v1/devices/tenant-devices",
    headers=headers
)
devices = response.json()