The GainingDocx API

Quickstart

1. 1Sign in and open Integrations in your workspace.
2. 2Create an API key. It is shown once — store it in your secret manager immediately.
3. 3Confirm it works by calling GET /v1/me.
4. 4Parse your first document with POST /v1/parse.

export GAININGDOCX_API_KEY="gdx_live_..."

curl https://gainingdocx.com/api/v1/me \
  -H "Authorization: Bearer $GAININGDOCX_API_KEY"

Authentication

Every request needs an Authorization: Bearer header carrying a key that starts with gdx_live_. Only a SHA-256 hash of the key is stored, so a database compromise does not hand over working credentials — and neither we nor you can recover a lost key. Create a new one and revoke the old.

Errors and rate limits

Every failure returns the same envelope, so you write one error handler rather than one per endpoint. Branch on code, which is stable; message is for humans and may be reworded.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "`cbm` must be a number.",
    "param": "cbm",
    "request_id": "req_8f2c1a94be7d40118c3e"
  }
}

Rate limiting is 120 requests per 60 seconds per key, counted in the database rather than per worker — so the limit is the real limit no matter which edge location serves you. Every response carries X-RateLimit-Remaining and X-Request-Id.

Endpoints

Base URL https://gainingdocx.com/api/v1 · OpenAPI spec

curl https://gainingdocx.com/api/v1/me \
  -H "Authorization: Bearer $GAININGDOCX_API_KEY"

{
  "object": "account",
  "plan": "pro",
  "api_key": { "name": "Production", "prefix": "gdx_live_" },
  "rate_limit": { "limit": 120, "remaining": 119 }
}

curl https://gainingdocx.com/api/v1/parse \
  -H "Authorization: Bearer $GAININGDOCX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pages": [{ "url": "https://example.com/bl-page-1.jpg" }],
    "document_type": "bill_of_lading"
  }'

{
  "id": "b2c1…",
  "object": "document",
  "status": "parsed",
  "document_type": "bill_of_lading",
  "fields": { "bl_number": "MEDUX1234567", "containers": [ … ] },
  "validation": [ { "field": "container_no", "severity": "error", … } ]
}

curl "https://gainingdocx.com/api/v1/documents?status=parsed&limit=10" \
  -H "Authorization: Bearer $GAININGDOCX_API_KEY"

curl https://gainingdocx.com/api/v1/tools/validate-reference \
  -H "Authorization: Bearer $GAININGDOCX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "container", "values": ["MSCU1234565", "TGHU7654321"] }'

{
  "object": "reference_validation",
  "valid_count": 1,
  "results": [
    { "input": "MSCU1234565", "valid": true, "expected_check_digit": 5 },
    { "input": "TGHU7654321", "valid": false,
      "expected_check_digit": 7, "suggested": "TGHU7654327" }
  ]
}

curl https://gainingdocx.com/api/v1/tools/volume \
  -H "Authorization: Bearer $GAININGDOCX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "unit": "cm",
    "groups": [{ "length": 120, "width": 80, "height": 95, "quantity": 4, "gross_weight": 260 }]
  }'

{
  "totals": {
    "volume_m3": 3.648,
    "actual_weight": 260,
    "volumetric_weight": 608,
    "chargeable_weight": 608,
    "rated_on": "volumetric"
  }
}

curl https://gainingdocx.com/api/v1/tools/freight-charges \
  -H "Authorization: Bearer $GAININGDOCX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "calculation": "lcl_wm",
    "cbm": 12.4, "gross_kg": 9800, "rate_per_revenue_ton": 48
  }'

curl "https://gainingdocx.com/api/v1/content/search?q=how+is+chargeable+weight+calculated" \
  -H "Authorization: Bearer $GAININGDOCX_API_KEY"

Webhooks

Rather than polling for a parse to finish, register an HTTPS endpoint in Integrations and receive document.parsed, document.failed and hs.reviewed events. Each delivery is signed with your endpoint’s secret so you can verify it came from us — always verify before acting on a payload.

API questions

How do I get an API key?

Sign in, open Integrations in your workspace, and create a key. The plaintext key is shown once at creation and only its SHA-256 hash is stored, so it cannot be recovered later — save it to your secret manager immediately. Keys can be revoked at any time and revocation takes effect on the next request.

What are the rate limits?

120 requests per 60 seconds per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a 429 additionally carries Retry-After. Counting happens in the database rather than per worker, so the limit is the real limit regardless of which edge location serves you.

Is the API versioned?

Yes. Every path is prefixed with /v1. Additive changes — new endpoints, new response fields — ship within v1. Anything that could break a working integration would ship as a new version, and error codes are treated as part of the contract even though messages are not.

Can I call the API from a browser?

No. API keys carry full account access and must never appear in browser or mobile code, where anyone can read them. Call the API from your server. CORS is permissive so server-side proxies and tools work, which is not an invitation to embed a key client-side.

How should I handle errors?

Every error returns the same envelope with a stable `code`, a human `message`, an optional `param` naming the offending input, and a `request_id`. Branch on `code`, show `message`, and quote `request_id` to support. Retry 429 after Retry-After and 5xx with exponential backoff; do not retry 400 or 401 without changing something.

Is there an OpenAPI specification?

Yes, at /api/v1/openapi.json. It is OpenAPI 3.1 and is maintained in the same commit as the routes, so you can generate a client, import it into Postman or Insomnia, and diff it between releases.