Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PDNMX/s1_backend/llms.txt

Use this file to discover all available pages before exploring further.

S1 Backend exposes a JSON REST API over HTTP that acts as a gateway to Mexico’s Plataforma Digital Nacional (PDN) Sistema 1. Clients do not need to authenticate — the gateway handles OAuth 2.0 internally against each configured provider on every request. All request and response bodies are JSON.

​
Base URL

The server listens on the port defined by the PORT environment variable, which defaults to 3000 (the .env.example file uses 3101). No path prefix is required — routes are mounted directly at the root. 
http://<host>:<PORT>
Example: 
http://localhost:3101

​
Authentication

Callers send no authentication headers. S1 Backend manages all provider credentials internally. On every outbound request to a provider, the gateway performs the OAuth 2.0 password grant flow:
  1. Posts grant_type=password along with username, password, client_id, client_secret (and optionally scope) to the provider’s token_url.
  2. The request uses HTTP Basic Auth with client_id and client_secret as credentials.
  3. The resulting access_token is attached as a Bearer token in the Authorization header of the subsequent data request.
Tokens are not cached. A fresh token is acquired from the provider on every inbound API call. Credentials are stored server-side in endpoints.json and are never exposed to callers.

​
Endpoints Summary

MethodPathDescription
GET/Returns the API title and version string
GET/v1/providersLists all configured data providers
POST/v1/summaryReturns record counts fanned out across matching providers
POST/v1/searchPaginated declaration search against one specific provider
POST/v1/loggerIngests an array of client-side log events

​
Request Format

All POST requests must send a Content-Type: application/json header and a JSON body. GET requests have no body. 
POST /v1/search HTTP/1.1
Host: localhost:3101
Content-Type: application/json

{
  "supplier_id": "EDOMEX",
  "page": 1,
  "pageSize": 10
}

​
Response Format

All responses are JSON. Successful responses return HTTP 200. Error responses use HTTP 500 with one of these body shapes: 
{ "error": "<message>" }

{ "error": { "status": 401, "statusText": "Unauthorized" } }
Individual provider failures inside /v1/summary do not cause a 500 response. Instead, the failed provider entry includes "error": "Algo salió mal." and "totalRows": "No disponible" in the summary array, while other providers’ results are still returned.

​
CORS

CORS is enabled globally via the cors middleware applied to all routes. All origins are permitted — no explicit allow-list is configured.

​
Pagination

Both /v1/search and /v1/summary accept page and pageSize fields in the request body to control pagination.
EndpointDefault pageDefault pageSize
POST /v1/search110
POST /v1/summary11
/v1/summary uses pageSize: 1 by default because it is only interested in the total record count (pagination.totalRows) returned by each provider — not the full result set. Use /v1/search when you need actual declaration records.

​
Explore Endpoints

Health Check

GET / — Verify the gateway is running and retrieve the API version.

Providers

GET /v1/providers — List all configured government data suppliers.

Summary

POST /v1/summary — Fan out a query and retrieve record counts from multiple providers simultaneously.

Search

POST /v1/search — Run a paginated, filterable search against one specific provider.

Logger

POST /v1/logger — Forward client-side log events to the server log.

Build docs developers (and LLMs) love

Get started for freeTalk to us