Developer API v2: What Shipped and How to Use It

The Tenders-SA Developer API v2 runs on a dedicated Cloudflare Worker at api.tenders-sa.org. It exposes 80+ endpoints across 17 resource groups — tenders, awards, organisations, suppliers, directors, categories, provinces, SEO content, industry benchmarks, services, OCDS parties, procurement intelligence, restricted supplier forensics, CIPC company data, newsletter editions, and document metadata. Every endpoint returns structured JSON with a consistent envelope, cursor-based pagination, and per-key rate limiting.

This is not a thin proxy over the main application database. The API runs against its own dedicated D1 database, synced from the main platform every five minutes via shared-secret authenticated cursor-based export endpoints. This separation means API traffic never competes with the user-facing website for database connections, and the Worker's global edge distribution provides sub-50ms cold starts regardless of where the caller is located.

Infrastructure Design

Understanding the infrastructure helps you reason about data freshness, reliability, and failure modes. The pipeline has three stages:

1. Main application (Next.js on AWS, PostgreSQL) — ingests tenders from National Treasury eTenders, Eskom, Transnet, SANRAL, provincial portals, and municipal systems. AI pipelines enrich each tender with summaries, requirement extraction, value estimation, and category classification.
2. Sync layer — 33 internal sync-export endpoints expose each entity as a paginated cursor-based stream. The Worker pulls delta changes every five minutes using the since and cursor parameters. Only rows with updatedAt newer than the last cursor are fetched — not full-table scans.
3. API Worker (Cloudflare, D1) — serves all public and authenticated endpoints from its own database. Validates API keys against SHA-256 hashes, enforces per-key daily and monthly rate limits, logs usage, and caches responses at the edge with TTLs ranging from 5 minutes (tender lists) to 6 hours (analytics).

The Worker exposes two health-check endpoints without authentication — /v2/meta/status and /v2/meta/health — that return per-table record counts and the most recent cron sync status. These are useful for monitoring dashboards and integration health checks.

Base URL and API Versioning

All API requests target the /v2/ prefix:

Copy
1https://api.tenders-sa.org/v2/{resource}
TEXT

The /v1/ prefix is not active on this Worker. If you are migrating from the previous API surface, all endpoint paths have changed. The v2 API uses cursor-based pagination instead of page-based, and resource paths follow a RESTful-by-resource convention.

Authentication

All data endpoints require a Bearer token in the Authorization header. Keys use the tsa_prod_ prefix:

Copy
1Authorization: Bearer tsa_prod_your_api_key
TEXT

Keys are SHA-256 hashed at rest in D1. The authentication flow validates the hash, checks the key status (must be ACTIVE), confirms the key has not expired, then evaluates per-key daily and monthly usage counters against the key's configured limits. Failed authentications return structured error responses with the specific failure reason (MISSING_API_KEY, INVALID_API_KEY, KEY_NOT_ACTIVE, or KEY_EXPIRED).

Rate Limiting

Every authenticated response returns rate limit information in both HTTP headers and the response body:

Copy
1X-RateLimit-Limit: 10000
2X-RateLimit-Remaining: 9847
3X-RateLimit-Reset: 2026-06-16T00:00:00.000Z
4X-RateLimit-Policy: daily
TEXT

The same data appears in the JSON response body under meta.rateLimit, so integrators that do not parse HTTP headers can read limit status from the envelope. When a limit is exceeded, the API returns HTTP 429 with either RATE_LIMIT_DAILY_EXCEEDED or RATE_LIMIT_MONTHLY_EXCEEDED, plus a Retry-After header and a resetsAt ISO timestamp in the response body.

Response Envelope

Every successful response follows this structure:

Copy
1{
2  "success": true,
3  "data": [ ],
4  "meta": {
5    "requestId": "req_67af5c2e",
6    "timestamp": "2026-06-15T10:04:14.318Z",
7    "apiVersion": "v2",
8    "totalCount": 5916,
9    "pageSize": 20,
10    "totalPages": 296,
11    "hasNext": true,
12    "hasPrev": false,
13    "rateLimit": {
14      "limit": 10000,
15      "remaining": 9847,
16// ... (truncated)
Show More (5 more lines)
JSON

Error responses use the same envelope shape but with success: false, an error message, a machine-readable code, and a docs URL pointing to the relevant error documentation:

Copy
1{
2  "success": false,
3  "error": "The provided API key is invalid or has been revoked",
4  "code": "INVALID_API_KEY",
5  "action": "API_KEY_REQUIRED",
6  "requestId": "req_a1b2c3d4",
7  "docs": "https://tenders-sa.org/developers/docs",
8  "timestamp": "2026-06-15T10:04:14.318Z"
9}
JSON

Pagination

List endpoints use cursor-based pagination. Every list response includes a nextCursor value in the meta. To retrieve the next page, pass this value as the cursor query parameter:

Copy
1GET /v2/tenders?limit=50&cursor=eyJpZCI6ImNs...
TEXT

Cursor-based pagination is stable under concurrent writes — unlike offset-based pagination, a cursor points to a specific row and will not skip or duplicate records when new data is inserted between requests. The totalCount field in the response meta gives the full dataset size, and hasNext / hasPrev booleans simplify client-side navigation logic.

Endpoint Catalogue

The full API surface is documented in an auto-generated OpenAPI 3.0 specification at /v2/openapi.json (no auth required) with an interactive Redocly viewer at /v2/docs. Below is a functional summary of every resource group.

Tenders — 27 endpoints

Awards — 12 endpoints

Organisations (Procurement Bodies) — 8 endpoints

Suppliers (Companies) — 9 endpoints

Directors, Categories, Provinces — 10 endpoints

SEO, Content, Industry, Services, OCDS — 14 endpoints

Intelligence, Forensic, CIPC, Newsletters, Documents, Meta — remainder

Public Endpoints (No Authentication)

Four endpoints are available without an API key. These serve monitoring, reference data, and documentation needs:

Working with the API: Key Patterns

Listing tenders with pagination

Copy
1# First page — no cursor
2curl -s "https://api.tenders-sa.org/v2/tenders?limit=10" \
3  -H "Authorization: Bearer tsa_prod_<key>" | jq '{count: .meta.totalCount, next: .meta.nextCursor, first: .data[0].title}'
4
5# Second page — pass the cursor from the first response
6curl -s "https://api.tenders-sa.org/v2/tenders?limit=10&cursor=eyJpZCI6ImNs..." \
7  -H "Authorization: Bearer tsa_prod_<key>" | jq '.data[].title'
BASH

Searching tenders

Copy
1curl -s "https://api.tenders-sa.org/v2/tenders/search?q=construction+western+cape" \
2  -H "Authorization: Bearer tsa_prod_<key>" | jq '.data[] | {title, province, closingDate}'
BASH

Supplier due diligence: forensic check

Copy
1# Check if a supplier appears on any restricted list
2curl -s "https://api.tenders-sa.org/v2/forensic/restricted-suppliers/check?q=ACME+Construction+Pty+Ltd" \
3  -H "Authorization: Bearer tsa_prod_<key>" | jq .
BASH

Award analytics by B-BBEE level

Copy
1curl -s "https://api.tenders-sa.org/v2/awards/analytics/bee-level" \
2  -H "Authorization: Bearer tsa_prod_<key>" | jq '.data'
BASH

Monitoring your API usage

Copy
1curl -s "https://api.tenders-sa.org/v2/meta/usage" \
2  -H "Authorization: Bearer tsa_prod_<key>" | jq .
BASH

Integration Use Cases

The endpoint catalogue supports several integration patterns that go beyond simple data retrieval:

• Compliance dashboards — Combine /v2/awards/analytics/bee-level with /v2/awards/analytics/province to build real-time B-BBEE spend visualisations. Filter by date range to track procurement transformation over time.
• Supplier risk screening — Before onboarding a new subcontractor or responding to a tender that requires joint venture partners, call /v2/forensic/restricted-suppliers/check?q={name} to verify the entity does not appear on government restricted supplier lists.
• Market opportunity tracking — Poll /v2/tenders/closing-soon and /v2/tenders/new on a schedule to populate opportunity feeds, email alerts, or internal CRM pipelines.
• Competitor intelligence — Use /v2/companies/{name}/awards to understand which contracts a competitor has won, at what values, and in which categories. Cross-reference with /v2/companies/{name}/tenders to see what they are bidding on.
• Content enrichment — Pull tender data into external websites, industry blogs, or newsletters. Use the /v2/tenders/{id} endpoint to get AI-summarised descriptions and structured requirement lists without parsing raw government PDFs.
• Procurement transparency reporting — Use /v2/organizations/{id}/tenders and /v2/awards/by-tender/{id} to audit procurement activity by department, track award concentration, or verify publication compliance.

OpenAPI Specification and Tooling

The API serves its own OpenAPI 3.0 specification at /v2/openapi.json. This spec is auto-generated from the Worker's D1 schema, which means it always reflects the actual deployed data surface — there is no separate hand-maintained spec file. The spec includes:

• All 17 tag groups with descriptions
• Every path, HTTP method, and parameter definition
• Response schemas derived from the D1 table columns
• Security scheme definition for Bearer token authentication
• A Redocly HTML viewer at /v2/docs

To use the spec with external tooling, point Postman, Insomnia, or any OpenAPI-compatible client at https://api.tenders-sa.org/v2/openapi.json

. The spec includes the production server URL, so imported collections are immediately callable after setting an API key.

SDKs

Three official SDKs are available in the monorepo under api-sdk-packages/:

• JavaScript / TypeScript — @tenders-sa-org/sdk-js on npm. Published via semantic-release on push to main. Uses the resource pattern: client.tenders.list(), client.awards.get(id).
• Python — tendersa-sdk on PyPI (alpha). Built with hatchling. Automatically converts camelCase API fields to snake_case Python attributes.
• CLI — @tenders-sa-org/cli on npm. Wraps the JS SDK. Supports piping output to jq and file redirection for scripting.

The SDKs handle authentication, pagination, error mapping to typed exceptions, rate limit tracking, and retry with exponential backoff for transient failures. The HTTP API is the stable surface — SDKs are convenience layers that reduce boilerplate.

Error Handling

Getting an API Key

API keys are generated through the main application at https://tenders-sa.org/developers/api-keys

. Each key is configurable with:

• A descriptive name for identifying the key's purpose (e.g. "CRM integration", "Analytics dashboard")
• A tier (Professional or Enterprise) that determines default rate limits
• Custom daily and monthly limits if the tier defaults need adjustment
• An optional expiry date for time-limited access

Keys can be revoked at any time from the same dashboard. Revocation takes effect immediately on the Worker — the key cache has a 5-minute TTL, after which the revocation propagates to all edge locations.

Data Freshness and Monitoring

Data is synced from the main application to the API Worker's D1 database every 5 minutes via a cron trigger. Each sync cycle processes up to 10 entities in priority order — entities that have never been synced or have unfinished cursors are prioritised. The sync uses the shared-secret-protected internal export endpoints and only fetches rows with updatedAt timestamps newer than the last completed cursor.

You can inspect the current state of the API database at any time through the public health endpoint:

Copy
1curl -s "https://api.tenders-sa.org/v2/meta/status" | jq '.data.entities'
2# Returns: { "tenders": 5916, "awards": 1800, "organizations": 764, ... }
BASH

The response includes the most recent cron run timestamp, its status, and rows synced in that run. For production integrations, poll this endpoint on a regular interval and alert if the last successful sync is older than your freshness tolerance.

Links