Companies Advanced Data

Base URL & versioning

The CadFiles API is versioned to protect clients from breaking changes. Prefer explicit versions in the URL.

Base: https://cadfiles.ai/api Version: /v1 Format: JSON

GET https://cadfiles.ai/api/v1/companies
GET https://cadfiles.ai/api/v1/companies/{id}

Tip: when you introduce v2, keep v1 stable for a period and publish a migration guide.

Authentication

Use Bearer tokens for authenticated API access. For server-to-server integrations, you can also support API keys (optional).

Bearer token

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://cadfiles.ai/api/v1/companies

Recommended for user-based access
Works well with role/permission checks

API key (optional)

curl -H "X-Api-Key: YOUR_KEY" \
  https://cadfiles.ai/api/v1/companies

Good for service accounts
Should be scoped + revocable

Security: always use HTTPS, rotate keys/tokens, and apply least privilege (roles/permissions).

Resource patterns

The API follows predictable REST patterns. Keep endpoints consistent and avoid surprises.

GET list GET single POST create PUT/PATCH update DELETE remove

GET    /api/v1/companies
GET    /api/v1/companies/{id}
POST   /api/v1/reports
GET    /api/v1/reports/{id}
DELETE /api/v1/api-keys/{id}   (if you offer keys)

Keep responses consistent: always return a predictable JSON shape, even for errors.

Pagination, filtering, sorting

Large datasets must be paginated. Add filtering and sorting to keep requests efficient.

Pagination

GET /api/v1/companies?page=1&per_page=25

page (default 1)
per_page (default 25, cap at e.g. 100)

Filtering & sorting

GET /api/v1/companies?country=RO&industry=CAEN:6201&sort=-updated_at

sort=name ascending
sort=-name descending

Recommended response shape

{
  "data": [ ... ],
  "meta": { "page": 1, "per_page": 25, "total": 9231 },
  "links": {
    "next": "https://cadfiles.ai/api/v1/companies?page=2&per_page=25",
    "prev": null
  }
}

Errors & status codes

Use standard HTTP status codes and return structured JSON errors clients can handle.

Common status codes

200 OK
201 Created
400 Bad request
401 Unauthorized
403 Forbidden
404 Not found
422 Validation error
429 Rate limit
500 Server error

Error JSON example

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request is invalid.",
    "details": {
      "company_id": ["The company_id field is required."]
    }
  }
}

Rate limits

Rate limiting prevents abuse and keeps the platform stable. Return helpful headers so clients can back off gracefully.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000

Client guidance: on 429, wait until X-RateLimit-Reset and retry with exponential backoff.

Idempotency

For POST endpoints that create something (reports, jobs, payments), accept an idempotency key so retries are safe.

POST /api/v1/reports
Idempotency-Key: 2b7b9b8e-4d2a-4d52-a19c-8f0f8e6d3f1a

If the same key is reused with the same payload, return the original result.
If the payload changes for the same key, return 409 Conflict.

Webhooks

Webhooks push events to your clients. Always sign payloads so receivers can verify authenticity.

Event examples

import.finished
report.ready
dataset.updated
template.changed

Webhook payload example

{
  "id": "evt_123",
  "type": "report.ready",
  "created_at": "2026-01-05T00:00:00Z",
  "data": {
    "company_id": 123,
    "report_id": 555,
    "download_url": "https://cadfiles.ai/api/v1/reports/555/download"
  }
}

Signing (recommended)

X-CadFiles-Signature: t=1700000000,v1=HMAC_SHA256_HEX(payload)

Receiver should verify signature + timestamp and reject old replays.

Async jobs

Long tasks (imports, large exports, PDF generation) should be asynchronous. Start the job, return an id, and let the client poll.

POST /api/v1/reports
{
  "company_id": 123,
  "layout_id": 55,
  "years": [2023, 2024]
}

=> 202 Accepted
{
  "job_id": "job_abcd1234"
}

GET /api/v1/jobs/job_abcd1234

{
  "status": "running",
  "progress": 62,
  "message": "Rendering page 8/14..."
}

Progress streaming (SSE)

For dashboards, Server-Sent Events are a cost-effective way to stream logs/progress to the browser.

GET /api/v1/jobs/job_abcd1234/stream

event: progress
data: {"progress":62,"message":"Rendering page 8/14..."}

File downloads

Reports and bulk exports are usually delivered as downloadable files (PDF/CSV/ZIP). Use signed URLs or token-protected endpoints.

GET /api/v1/reports/555/download
=> Content-Type: application/pdf

Changelog

Keep a simple changelog so integrators can track updates.

v1 — Initial public endpoints (companies, reports, downloads)
v1.x — Non-breaking additions (new fields, new filters)
v2 — Breaking changes (announced with migration guide)

Tip: publish OpenAPI/Swagger and a Postman collection — cheapest “pro” docs upgrade.

CadFiles API Documentation