Partner API Docs (Scalar)

The partner API reference is hosted on Scalar Pro. The spec is generated at runtime from the NestJS Swagger module and served at /api/openapi.json.

Environments

Environment	OpenAPI spec URL	Hosted docs
Dev (personal tunnel)	https://<your-tunnel>/api/openapi.json	Published manually — see below
Production	https://api.tell-ia.com/api/openapi.json	scalar.config.json

The spec endpoint is only active when SWAGGER_ENABLED=true is set in the environment.

Config files

Two Scalar config files live at the repo root:

File	Purpose
scalar.dev.config.json	Points to the dev tunnel URL — used for publishing previews
scalar.config.json	Points to the production API — used for the live docs site

The config files define the navigation structure, doc pages (markdown files under docs/partner-api/), and the OpenAPI spec URL.

Publishing dev docs

To publish a preview of the partner API docs from your local branch:

1. Make sure your dev tunnel is running and SWAGGER_ENABLED=true is set
2. Update the url in scalar.dev.config.json to point to your tunnel URL if needed
3. Run:

SCALAR_API_KEY=xxxx npx @scalar/cli project publish \
  --config scalar.dev.config.json \
  --slug tell-ia-tell-ia-solutions

The SCALAR_API_KEY is in 1Password under Scalar API Key.

How the spec is generated

The OpenAPI spec is built by SwaggerModule.createDocument() in apps/agri-backend/src/main.ts. Only modules explicitly listed in the include array are included:

SwaggerModule.createDocument(app, swaggerConfig, {
  include: [
    WorkspaceModule,
    ParseModule,
    FieldModule,
    CallLogsModule,
    AggKnowledgeModule,
  ],
});

Endpoints decorated with @ApiExcludeEndpoint() or belonging to a controller decorated with @ApiExcludeController() are hidden from the spec.

Adding a new endpoint to the partner API

1. Add @ApiOperation, @ApiParam/@ApiQuery, and @ZodApiResponse decorators to the controller method
2. Make sure the module is in the include list in main.ts
3. Do not add @ApiExcludeEndpoint() — that hides the endpoint from the spec

Use ZodApiResponse (from src/common/swagger/zod-to-swagger.ts) rather than raw @ApiResponse with inline examples — it generates a proper typed schema from the Zod definition:

import { ZodApiResponse } from 'src/common/swagger/zod-to-swagger';
import { MyResponseSchema } from '@tellia-solutions/schemas';

@ZodApiResponse(200, MyResponseSchema, 'Description')
@Get(':id')
async findOne(@Param('id') id: string): Promise<MyResponse> { ... }

Response schemas that are consumed by the frontend or mobile app must live in packages/schemas/. Backend-only shapes can be defined locally in the controller file.