{"openapi":"3.1.1","info":{"title":"Twenty Api","description":"Use this page to explore and call the **REST API**.\n\n## Authentication\n\nSend a Bearer token with each request:\n\n```http\nAuthorization: Bearer <token>\n```\n\nExample cURL:\n\n```bash\ncurl -H 'Authorization: Bearer <token>' <server>/rest/core/companies\n```\n\nTokens can be generated in Settings → Playground and are workspace-scoped.\n\n> **Never put your token in a URL.** Tokens passed as query parameters end up in\n> server access logs, browser history, and `Referer` headers, which is why the\n> API only accepts tokens from the `Authorization` header.\n\n\n## Filters\n\nUse the `filter` query parameter to narrow results.\n\n- Format: `field[COMPARATOR]:value`\n- Multiple conditions: `field1[eq]:1,field2[gte]:10` (root conjunction is AND)\n- Composite fields: `field.subField[COMPARATOR]:value`\n- Common comparators: `eq`, `neq`, `in`, `containsAny`, `is`, `gt`, `gte`, `lt`, `lte`, `startsWith`, `like`, `ilike`\n- Wildcards: For `like`/`ilike`, use `%` as a wildcard (e.g. `%value%` for substring match)\n\nExamples:\n\n```text\nfilter=status[eq]:\"open\"\nfilter=createdAt[gte]:\"2024-01-01\"\nfilter=owner.name[ilike]:\"%smith%\"\nfilter=id[in]:[\"id-1\",\"id-2\"]\nfilter=deletedAt[is]:NULL\nfilter=isActive[eq]:true\n```\n\nAdvanced (optional): `and(...)`, `or(...)`, `not(...)` (`not` wraps one condition)\n\n```text\nfilter=or(status[eq]:\"open\",assigneeId[is]:NULL)\n```\n\nNotes: Strings and dates are quoted; numbers are not.\n\n## Pagination and ordering\n\nAll list endpoints use cursor-based pagination.\n\n- Use **limit** to cap page size (default: 60, max: 60).\n- Use **starting_after** to fetch the next page (forward).\n- Use **ending_before** to fetch the previous page (backward).\n- Responses include **pageInfo** with `hasNextPage`, `startCursor`, and `endCursor`.\n\nExamples:\n\n```bash\n# First page\ncurl -H 'Authorization: Bearer <token>' \\\n  '<server>/rest/core/companies?limit=60'\n\n# Next page\ncurl -H 'Authorization: Bearer <token>' \\\n  '<server>/rest/core/companies?limit=60&starting_after=<endCursorFromPreviousPage>'\n\n# Previous page\ncurl -H 'Authorization: Bearer <token>' \\\n  '<server>/rest/core/companies?limit=60&ending_before=<startCursorFromCurrentPage>'\n```\n\nYou can combine pagination with filters and ordering.\n\nOrdering with `order_by`:\n- Shape: `field1,field2[DIRECTION2]`\n- Directions: AscNullsFirst, AscNullsLast, DescNullsFirst, DescNullsLast\n- Default per-field direction: AscNullsFirst\n\nExamples:\n```text\norder_by=createdAt\norder_by=id[AscNullsFirst],createdAt[DescNullsLast]\n```\n\n## Usage with LLMs\n\nThe recommended way to give an LLM agent (Claude Desktop, Cursor, Windsurf, …)\naccess to your workspace is the **Twenty MCP server**, not this OpenAPI schema.\nThe MCP server exposes typed tools the agent can call directly with proper\nheader-based auth (OAuth or API key), no tokens in URLs.\n\nConfigure it from **Settings → AI → MCP** in your workspace. The endpoint is:\n\n```text\nhttps://api.twenty.com/mcp\n```\n\nIf you specifically need the raw OpenAPI document (for code generation, type\ngeneration, etc.), download it locally with a header-authenticated request and\nhand the file to your tool — never paste a tokenized URL into a chat:\n\n```bash\ncurl -H 'Authorization: Bearer <token>' \\\n  https://api.twenty.com/rest/open-api/metadata > twenty-metadata.json\n```\n","termsOfService":"https://github.com/twentyhq/twenty?tab=coc-ov-file#readme","contact":{"email":"felix@twenty.com"},"license":{"name":"AGPL-3.0","url":"https://github.com/twentyhq/twenty?tab=License-1-ov-file#readme"},"version":"v0.1"},"servers":[{"url":"https://api.twenty.com/rest/metadata","description":"Production Development"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Enter the token with the `Bearer: ` prefix, e.g. \"Bearer abcde12345\"."}}},"security":[{"bearerAuth":[]}],"externalDocs":{"description":"Find out more about **Twenty**","url":"https://twenty.com"},"paths":{"/open-api/metadata":{"get":{"tags":["General"],"summary":"Get Open Api Schema","operationId":"GetOpenApiSchema","servers":[{"url":"https://api.twenty.com"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"openapi":{"type":"string"},"info":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"termsOfService":{"type":"string"},"contact":{"type":"object","properties":{"email":{"type":"string"}}},"license":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}}}}},"servers":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"description":{"type":"string"}}}},"components":{"type":"object","properties":{"schemas":{"type":"object"},"parameters":{"type":"object"},"responses":{"type":"object"}}},"paths":{"type":"object"},"tags":{"type":"object"}}}}}}}}}}}