{ "openapi": "3.1.0", "info": { "title": "TruSupplier API", "version": "1.0.0", "description": "Supplier compliance API. Authenticate with an API key from Settings > API & MCP: Authorization: Bearer . Rate limit: 120 requests per minute per key." }, "servers": [ { "url": "https://app.trusupplier.co.za/api/v1" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key, starts with tsk_live_" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object" } }, "required": [ "code", "message" ] } } } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/suppliers": { "get": { "operationId": "list_suppliers", "summary": "List suppliers", "description": "List your company's suppliers (archived ones are hidden). Filter by name search or registration number.", "tags": [ "Suppliers" ], "x-scope": "read", "x-mcp-tool": "list_suppliers", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search legal or trading name" }, { "name": "registration_no", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Exact company registration number, e.g. 2015/123456/07" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Max rows, 1-200 (default 50)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to skip (default 0)" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "create_supplier", "summary": "Add a supplier", "description": "Add a supplier. Fails with 409 if a supplier with the same registration number already exists. Does not run any paid checks. Scope: write.", "tags": [ "Suppliers" ], "x-scope": "write", "x-mcp-tool": "create_supplier", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "legal_name": { "type": "string", "description": "Registered company name" }, "trading_name": { "type": "string", "description": "Trading name" }, "registration_no": { "type": "string", "description": "Company registration number" }, "vat_no": { "type": "string", "description": "VAT number" }, "website": { "type": "string", "description": "Website" }, "physical_address": { "type": "string", "description": "Address" }, "annual_spend": { "type": "number", "description": "Annual spend with this supplier (ZAR)" } }, "required": [ "legal_name" ] } } } }, "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/suppliers/{id}": { "get": { "operationId": "get_supplier", "summary": "Get a supplier", "description": "One supplier's profile and compliance status.", "tags": [ "Suppliers" ], "x-scope": "read", "x-mcp-tool": "get_supplier", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Supplier id (UUID)" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "update_supplier", "summary": "Update a supplier", "description": "Change a supplier's basic details. Only the fields you send change. Scope: write.", "tags": [ "Suppliers" ], "x-scope": "write", "x-mcp-tool": "update_supplier", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Supplier id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "legal_name": { "type": "string", "description": "Registered name" }, "trading_name": { "type": "string", "description": "Trading name" }, "registration_no": { "type": "string", "description": "Registration number" }, "vat_no": { "type": "string", "description": "VAT number" }, "website": { "type": "string", "description": "Website" }, "physical_address": { "type": "string", "description": "Address" }, "postal_address": { "type": "string", "description": "Postal address" }, "annual_spend": { "type": "number", "description": "Annual spend (ZAR)" } } } } } }, "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/suppliers/by-registration/{registration_no}": { "get": { "operationId": "get_supplier_by_registration", "summary": "Find a supplier by registration number", "description": "Look up a supplier by company registration number (slashes optional, e.g. 2015/123456/07 or 201512345607).", "tags": [ "Suppliers" ], "x-scope": "read", "x-mcp-tool": "get_supplier_by_registration", "parameters": [ { "name": "registration_no", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Company registration number" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/suppliers/{id}/archive": { "post": { "operationId": "archive_supplier", "summary": "Archive a supplier", "description": "Archive (soft-delete) a supplier. It disappears from lists; history is kept. Scope: write.", "tags": [ "Suppliers" ], "x-scope": "write", "x-mcp-tool": "archive_supplier", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Supplier id" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/checks/types": { "get": { "operationId": "list_check_types", "summary": "List check types and prices", "description": "Checks you can run on a supplier, with the price in credits (ZAR), plus your available credit balance.", "tags": [ "Checks" ], "x-scope": "read", "x-mcp-tool": "list_check_types", "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/checks/run": { "post": { "operationId": "run_checks", "summary": "Run checks (costs credits)", "description": "Run checks on suppliers. COSTS CREDITS. Without confirm=true this only returns a quote (cost, balance, whether you have enough) and charges nothing. Show the quote to the user and only call again with confirm=true once they agree. Needs the run_checks scope. Scope: run_checks.", "tags": [ "Checks" ], "x-scope": "run_checks", "x-mcp-tool": "run_checks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_ids": { "type": "array", "items": { "type": "string" }, "description": "Supplier ids" }, "check_types": { "type": "array", "items": { "type": "string" }, "description": "Check type ids from list_check_types" }, "confirm": { "type": "boolean", "description": "true = start the checks and spend the credits. Omit or false = quote only." } }, "required": [ "supplier_ids", "check_types" ] } } } }, "responses": { "200": { "description": "OK" }, "202": { "description": "Checks started (confirm=true)" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/checks/results": { "get": { "operationId": "list_check_results", "summary": "List check results", "description": "Finished check results, newest first. Filter by supplier.", "tags": [ "Checks" ], "x-scope": "read", "x-mcp-tool": "list_check_results", "parameters": [ { "name": "supplier_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this supplier" }, { "name": "check_type_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this check type" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Max rows, 1-200 (default 50)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to skip (default 0)" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/checks/results/{id}": { "get": { "operationId": "get_check_result", "summary": "Get a check result", "description": "One check result including the provider's detailed answer.", "tags": [ "Checks" ], "x-scope": "read", "x-mcp-tool": "get_check_result", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Check result id" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/checks/runs": { "get": { "operationId": "list_check_runs", "summary": "List check runs", "description": "Checks that were requested and their status (requested, running, done, failed).", "tags": [ "Checks" ], "x-scope": "read", "x-mcp-tool": "list_check_runs", "parameters": [ { "name": "supplier_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this supplier" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Max rows, 1-200 (default 50)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to skip (default 0)" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/documents": { "get": { "operationId": "list_documents", "summary": "List documents", "description": "Supplier documents (certificates, letters, statements) on file.", "tags": [ "Documents" ], "x-scope": "read", "x-mcp-tool": "list_documents", "parameters": [ { "name": "supplier_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this supplier" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Max rows, 1-200 (default 50)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to skip (default 0)" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "upload_document", "summary": "Upload a document", "description": "Upload a supplier document (PDF or image, max 10 MB). REST: multipart/form-data with 'file'. MCP: send content_base64 and filename. The document is filed on the supplier and read automatically. Scope: write.", "tags": [ "Documents" ], "x-scope": "write", "x-mcp-tool": "upload_document", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "supplier_id" ], "properties": { "file": { "type": "string", "format": "binary" }, "supplier_id": { "type": "string" }, "evidence_type_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/documents/{id}": { "get": { "operationId": "get_document", "summary": "Get a document", "description": "One document's details and the fields read from it. Download the file itself with GET /documents/{id}/file (REST only).", "tags": [ "Documents" ], "x-scope": "read", "x-mcp-tool": "get_document", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Document id" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/requests": { "get": { "operationId": "list_requests", "summary": "List document requests", "description": "Document requests sent to suppliers and their status (queued, sent, opened, submitted, expired).", "tags": [ "Requests" ], "x-scope": "read", "x-mcp-tool": "list_requests", "parameters": [ { "name": "supplier_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this supplier" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this status" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Max rows, 1-200 (default 50)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to skip (default 0)" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/requests/send": { "post": { "operationId": "send_requests", "summary": "Send document requests", "description": "Email each supplier one request for everything they still owe (outstanding required documents). This sends real emails to the suppliers' contacts. Scope: write.", "tags": [ "Requests" ], "x-scope": "write", "x-mcp-tool": "send_requests", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplier_ids": { "type": "array", "items": { "type": "string" }, "description": "Supplier ids" }, "reminder": { "type": "boolean", "description": "true = send as a reminder" } }, "required": [ "supplier_ids" ] } } } }, "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/bbbee/summary": { "get": { "operationId": "get_bbbee_summary", "summary": "B-BBEE summary", "description": "Your suppliers grouped by B-BBEE level, with spend per level and how many certificates are expired or missing.", "tags": [ "B-BBEE" ], "x-scope": "read", "x-mcp-tool": "get_bbbee_summary", "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/billing/balance": { "get": { "operationId": "get_balance", "summary": "Credit balance", "description": "Your credit wallet: balance, amount reserved for running checks, and what's available.", "tags": [ "Billing" ], "x-scope": "read", "x-mcp-tool": "get_balance", "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/billing/transactions": { "get": { "operationId": "list_transactions", "summary": "Credit transactions", "description": "Credit wallet transactions (top-ups, check charges), newest first.", "tags": [ "Billing" ], "x-scope": "read", "x-mcp-tool": "list_transactions", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Max rows, 1-200 (default 50)" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to skip (default 0)" } ], "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/documents/{id}/file": { "get": { "operationId": "download_document", "summary": "Download a document file", "tags": [ "Documents" ], "x-scope": "read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file", "content": { "application/octet-stream": {} } }, "404": { "$ref": "#/components/responses/Error" } } } }, "/me": { "get": { "operationId": "whoami", "summary": "Check your key", "tags": [ "Authentication" ], "x-scope": "read", "responses": { "200": { "description": "Company id, key prefix and scopes" }, "401": { "$ref": "#/components/responses/Error" } } } } }, "x-mcp": { "url": "https://app.trusupplier.co.za/mcp", "transport": "streamable-http" } }