openapi: 3.0.3 info: title: ffwd server API version: "1.0.0" description: > HTTP API served by `ffwd-server`. Each loaded model has an operator-chosen label; request `model` fields match that label. Embedding encoding follows the serving API selected at load time (`api=openai` or `api=perplexity`). Always compare embeddings with cosine similarity. license: name: MIT servers: - url: http://127.0.0.1:8000 # Auth is optional: it applies only when the server is started with --api-key # (or FFWD_API_KEY). The empty requirement allows unauthenticated calls. security: - {} - bearerAuth: [] paths: /v1/embeddings: post: summary: Create pooled embeddings operationId: createEmbeddings requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/EmbeddingsRequest" } responses: "200": description: One embedding per input, in request order. content: application/json: schema: { $ref: "#/components/schemas/EmbeddingsResponse" } "422": { $ref: "#/components/responses/ValidationError" } /v1/contextualizedembeddings: post: summary: Create contextual (late-chunking) document embeddings operationId: createContextualizedEmbeddings description: > Each document is a list of chunk strings. Chunks are embedded with document-level context and returned per document, per chunk, in order. requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/ContextualRequest" } responses: "200": description: One list of chunk embeddings per document, in order. content: application/json: schema: { $ref: "#/components/schemas/ContextualResponse" } "422": { $ref: "#/components/responses/ValidationError" } /v1/rerank: post: summary: Late-interaction (MaxSim) reranking operationId: rerank description: > Scores each document against the query with token-level MaxSim and returns documents ranked by raw score (not a probability). requestBody: required: true content: application/json: schema: { $ref: "#/components/schemas/RerankRequest" } responses: "200": description: Documents ranked by descending relevance score. content: application/json: schema: { $ref: "#/components/schemas/RerankResponse" } "422": { $ref: "#/components/responses/ValidationError" } components: securitySchemes: bearerAuth: type: http scheme: bearer description: > Single shared token set with --api-key. Not a real auth system; terminate TLS and authenticate at a reverse proxy in production. schemas: EmbeddingsRequest: type: object required: [model, input] properties: model: type: string description: Served label chosen when starting `ffwd-server`. example: qwen input: description: A single string or an array of up to 512 strings. oneOf: - type: string - type: array items: { type: string } minItems: 1 maxItems: 512 encoding_format: type: string description: > Output encoding, validated against the serving API selected for the loaded label. `api=openai` accepts `float` (default; true float32) and `base64` (base64 of little-endian float32). `api=perplexity` accepts `base64_int8` (default), `base64_binary` (sign bits, needs `dimensions` divisible by 8), and `float` (the int8-decoded view). A format outside the label's serving API returns 422. enum: [float, base64, base64_int8, base64_binary] dimensions: type: integer description: > Matryoshka truncation, from the configured load-time `min_dim` up to the model's native dimension. Truncated normalized vectors are re-normalized. EmbeddingsResponse: type: object properties: object: { type: string, example: list } data: type: array items: { $ref: "#/components/schemas/Embedding" } model: { type: string } usage: { $ref: "#/components/schemas/Usage" } Embedding: type: object properties: object: { type: string, example: embedding } index: { type: integer } embedding: description: > A float array when `encoding_format` is `float`, otherwise a base64 string (`base64`, `base64_int8`, or `base64_binary`). oneOf: - type: array items: { type: number, format: float } - type: string ContextualRequest: type: object required: [model, input] properties: model: type: string description: Served contextual-model label. example: pplx-context input: description: Array of documents; each document is an array of chunk strings. type: array items: type: array items: { type: string } minItems: 1 encoding_format: type: string enum: [float, base64, base64_int8, base64_binary] dimensions: { type: integer } ContextualResponse: type: object properties: object: { type: string, example: list } data: type: array description: One entry per document, in request order. items: type: object properties: object: { type: string, example: list } index: { type: integer } data: type: array description: One embedding per chunk, in document order. items: { $ref: "#/components/schemas/Embedding" } model: { type: string } usage: { $ref: "#/components/schemas/Usage" } RerankRequest: type: object required: [model, query, documents] properties: model: type: string description: Served late-model label. example: pplx-late query: { type: string } documents: type: array items: { type: string } minItems: 1 maxItems: 1000 top_n: type: integer description: Number of results to return. Defaults to all. `top_k` is an alias. top_k: type: integer return_documents: type: boolean default: false description: Include the source document text in each result. additionalProperties: false RerankResponse: type: object properties: object: { type: string, example: list } model: { type: string } results: type: array items: type: object properties: index: type: integer description: Index of the document in the request array. relevance_score: type: number format: float description: Raw MaxSim score (not a probability). document: type: string description: Present only when `return_documents` is true. usage: type: object properties: query_tokens: { type: integer } document_tokens: { type: integer } total_tokens: { type: integer } Usage: type: object properties: prompt_tokens: { type: integer } total_tokens: { type: integer } ValidationDetail: type: object properties: loc: type: array description: Path to the offending field, e.g. ["body","input",0]. items: {} msg: { type: string } type: { type: string } ValidationError: type: object properties: detail: type: array items: { $ref: "#/components/schemas/ValidationDetail" } responses: ValidationError: description: Request body failed validation. content: application/json: schema: { $ref: "#/components/schemas/ValidationError" }