--- updatedAt: 2026-09-01T18:27:00.000Z agentTools: projectIndex: https://docs.api.getrotor.com/llms.txt --- # Get company configuration Returns the company's configured vocabularies — the values its records are allowed to carry, as set up in Settings. Each list is in the order the company arranged it, and any of them may be empty. These are the values the rest of this API expects: `service_type` filters take a name from `service_types`, `tags` filters take names from `tags`, and so on. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Rotor OpenAPI", "description": "Public-facing API for Rotor — a CRM and field service platform built for home service businesses.\n\nCurrent version: `1.1.0`\n\n## Authentication\n\nAll requests must be authenticated with a company API key.\n\n- Header: `x-api-key: rotor_{keyId}_{keySecret}`\n- Version header: `rotor-api-version: 1.1.0`\n\nAPI keys are scoped to a specific company and can be managed by company administrators in **Settings → Integrations → API Keys**.\n\n## Rate Limits\n\nEach API key is limited to **1000 requests per UTC day** across all OpenAPI endpoints.\n\n## Scopes\n\nEach API key is granted specific scopes that control what actions it can perform:\n\n| Scope | Description |\n|---|---|\n| `leads:create` | Create and update leads |\n| `leads:read` | Read lead records |\n| `customers:create` | Create and update customers |\n| `customers:read` | Read customer records |\n| `service_plans:read` | Read service plan records |\n| `jobs:read` | Read serviced job records |\n| `pins:read` | Read pin records and pin types |\n| `timesheets:read` | Read timesheet records and visit timer records |\n| `tasks:read` | Read task records |\n| `tasks:create` | Create tasks |\n| `tasks:update` | Update tasks |\n| `configuration:read` | Read company configuration (service types, line item templates) |\n\n## Getting Started\n\n1. **Set the required version header**: Send `rotor-api-version: 1.1.0` with every request\n2. **Create an API key**: Go to Settings → Integrations → API Keys, create a key with the scopes you need\n3. **For testing**: Use `GET /auth/test` to verify your credentials\n", "version": "1.1.0", "contact": { "name": "Rotor API Support", "url": "https://getrotor.com" } }, "servers": [ { "url": "https://api.getrotor.com/open-api", "description": "Production server" }, { "url": "http://localhost:3000/open-api", "description": "Development server" } ], "security": [ { "ApiKey": [] } ], "paths": { "/configuration": { "get": { "summary": "Get company configuration", "description": "Returns the company's configured vocabularies — the values its records are\nallowed to carry, as set up in Settings. Each list is in the order the\ncompany arranged it, and any of them may be empty.\n\nThese are the values the rest of this API expects: `service_type` filters\ntake a name from `service_types`, `tags` filters take names from `tags`,\nand so on.\n", "operationId": "getConfiguration", "tags": [ "Configuration" ], "security": [ { "ApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/RotorApiVersionHeader" } ], "responses": { "200": { "description": "Configuration retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/Configuration" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "parameters": { "RotorApiVersionHeader": { "name": "rotor-api-version", "in": "header", "description": "Required OpenAPI version header.", "required": true, "schema": { "type": "string", "enum": [ "1.1.0" ], "default": "1.1.0" }, "example": "1.1.0" } }, "responses": { "Unauthorized": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Authentication required. Provide x-api-key header.", "error_code": "AUTHENTICATION_REQUIRED" } } } }, "Forbidden": { "description": "Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Forbidden: required scope 'leads:read' not granted for this API key", "error_code": "INSUFFICIENT_SCOPE" } } } }, "TooManyRequests": { "description": "Daily API key rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Daily API key request limit of 1000 exceeded", "error_code": "RATE_LIMIT_EXCEEDED" } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Internal server error" } } } } }, "schemas": { "ErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Validation failed" }, "error_code": { "type": "string", "description": "Machine-readable error code", "example": "INSUFFICIENT_SCOPE" }, "limit": { "type": "integer", "description": "Daily request limit for the API key when rate limited", "example": 1000 }, "requests_today": { "type": "integer", "description": "Number of requests already consumed today by the API key", "example": 1000 }, "reset_at": { "type": "string", "format": "date-time", "description": "UTC timestamp when the daily request counter resets", "example": "2026-03-31T00:00:00Z" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "email" }, "message": { "type": "string", "example": "Invalid email format" } } } } } }, "Configuration": { "type": "object", "description": "The company's configured vocabularies. Every list is user-maintained in Settings and may be empty.\n", "properties": { "service_types": { "type": "array", "items": { "type": "string" }, "description": "Top-level price book folders, and the values `service_type` filters elsewhere in this API expect.\n", "example": [ "Window Cleaning", "Pressure Washing" ] }, "service_frequencies": { "type": "array", "items": { "type": "string" }, "example": [ "Monthly", "Quarterly" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag vocabulary shared by leads and customers", "example": [ "VIP", "Commercial" ] }, "lead_sources": { "type": "array", "items": { "type": "string" }, "example": [ "Referral", "Google" ] }, "service_plan_cancel_reasons": { "type": "array", "items": { "type": "string" }, "example": [ "Too expensive", "Moved" ] }, "opportunity_lost_reasons": { "type": "array", "items": { "type": "string" }, "example": [ "Went with competitor", "No budget" ] }, "manual_payment_methods": { "type": "array", "items": { "type": "string" }, "description": "Payment methods recorded by hand, outside Stripe", "example": [ "Cash", "Check" ] } }, "required": [ "service_types", "service_frequencies", "tags", "lead_sources", "service_plan_cancel_reasons", "opportunity_lost_reasons", "manual_payment_methods" ] } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Company API key in the format: `rotor_{keyId}_{keySecret}`\n\nTo obtain an API key:\n1. Log into your Rotor dashboard\n2. Go to Settings → Integrations → API Keys\n3. Create a new key and select the scopes you need\n4. Copy the key — it's only shown once!\n" } } }, "tags": [ { "name": "Configuration", "description": "Read company configuration — service types and line item templates" } ] } ```