{
  "schemaVersion": "1.0",
  "title": "Twenty capabilities",
  "description": "Use this index to choose the Twenty operation family that owns a task and interpret its AIP contract before invocation. The reviewed connector contains 22 fixed operations across records, workspace metadata, and OpenAPI documents.",
  "canonical": "https://getaip.org/docs/connectors/twenty/capabilities",
  "route": "/docs/connectors/twenty/capabilities",
  "source": "docs/connectors/twenty/capabilities/README.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "downloads": {
    "md": "/docs/download/connectors/twenty/capabilities.md",
    "txt": "/docs/download/connectors/twenty/capabilities.txt",
    "json": "/docs/download/connectors/twenty/capabilities.json",
    "pdf": "/docs/download/connectors/twenty/capabilities.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Twenty capabilities\ndescription: >-\n  Choose one of 22 fixed Twenty operations and interpret its complete AIP\n  policy contract\nkind: index\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\nconnector: twenty\naliases:\n  - Twenty capability index\n  - Twenty operations\n  - Twenty REST mapping\n---\n\n# Twenty capabilities\n\nUse this index to choose the Twenty operation family that owns a task and\ninterpret its AIP contract before invocation. The reviewed connector contains\n22 fixed operations across records, workspace metadata, and OpenAPI documents.\n\nThe source-derived machine snapshot owns the ordered inventory. Focused pages\nown input details and task guidance; neither artifact replaces authenticated\ntenant discovery.\n\n## Catalogue identity\n\n| Property | Reviewed value |\n|---|---|\n| AIP source | `97be86e9efedf07ecf1783b03800f683f107fb04` |\n| Provider mapping source | `96a24563674313a3071d359bfccaf33d5e130ab8` |\n| Connector profile | `aip.connector.twenty.v1` |\n| Capability prefix | `cap:twenty:` |\n| Frozen operations | 22 |\n| Reads and mutations | 8 and 14 |\n| Low, high, and critical risk | 8, 9, and 5 |\n| Approval required | 14 |\n| Idempotency key required | 14 |\n| Connector retry support | 11 |\n\nAn operations file can admit any non-empty subset. The full source catalogue\ncount is therefore not the capability count of every running manifest.\n\n## Read a capability ID\n\nEvery capability appends its exact operation suffix:\n\n```text\ncap:twenty:record.list\n│          │      └─ operation\n│          └──────── resource family\n└─────────────────── connector namespace\n```\n\nOther examples are:\n\n```text\ncap:twenty:record.create_many\ncap:twenty:metadata.update\ncap:twenty:openapi.core\n```\n\nDo not derive a capability from a provider route or GraphQL operation. Use the\nadmitted manifest or the source-derived snapshot.\n\n## Choose a family\n\n| Family | Focused page | Total | Read | Mutation | Primary use |\n|---|---|---:|---:|---:|---|\n| Record query and aggregation | `record-query-and-aggregation.md` | 4 | 4 | 0 | List, get, detect duplicates, and group records |\n| Record create, update, and batch upsert | `record-create-update-and-batch-upsert.md` | 4 | 0 | 4 | Create or update standard and custom records |\n| Record delete, restore, and merge | `record-delete-restore-and-merge.md` | 7 | 0 | 7 | Change record lifecycle or consolidate duplicates |\n| Workspace metadata | `workspace-metadata.md` | 5 | 2 | 3 | Read and change twelve fixed metadata resource types |\n| OpenAPI documents | `openapi-documents.md` | 2 | 2 | 0 | Read current core and metadata descriptions |\n| **Total** |  | **22** | **8** | **14** |  |\n\nSelect the focused page before constructing input. Similar HTTP methods do not\nmake operation schemas or safety contracts interchangeable.\n\n## Compare all operations\n\n| Operation | Method | Kind | Risk | Approval | Key | Retry |\n|---|---|---|---|---:|---:|---:|\n| `record.list` | GET | Tool | Low | No | Optional | Yes |\n| `record.get` | GET | Tool | Low | No | Optional | Yes |\n| `record.find_duplicates` | POST | Tool | Low | No | Optional | Yes |\n| `record.group_by` | GET | Tool | Low | No | Optional | Yes |\n| `record.create` | POST | Tool | High | Yes | Required | Yes |\n| `record.create_many` | POST | Tool | High | Yes | Required | Yes |\n| `record.update` | PATCH | Tool | High | Yes | Required | Yes |\n| `record.update_many` | PATCH | Tool | High | Yes | Required | No |\n| `record.soft_delete` | DELETE | Tool | High | Yes | Required | No |\n| `record.soft_delete_many` | DELETE | Tool | High | Yes | Required | No |\n| `record.destroy` | DELETE | Tool | Critical | Yes | Required | No |\n| `record.destroy_many` | DELETE | Tool | Critical | Yes | Required | No |\n| `record.restore` | PATCH | Tool | High | Yes | Required | No |\n| `record.restore_many` | PATCH | Tool | High | Yes | Required | No |\n| `record.merge` | PATCH | Tool | High | Yes | Required | No |\n| `metadata.list` | GET | Tool | Low | No | Optional | Yes |\n| `metadata.get` | GET | Tool | Low | No | Optional | Yes |\n| `metadata.create` | POST | Tool | Critical | Yes | Required | No |\n| `metadata.update` | PATCH | Tool | Critical | Yes | Required | No |\n| `metadata.delete` | DELETE | Tool | Critical | Yes | Required | No |\n| `openapi.core` | GET | Resource | Low | No | Optional | Yes |\n| `openapi.metadata` | GET | Resource | Low | No | Optional | Yes |\n\n`record.find_duplicates` is a read despite its provider POST method.\n`record.update` advertises safe retry with its required idempotency key, while\nthe filtered `record.update_many` operation does not.\n\n`Retry` describes connector contract support. It does not authorize an\napplication to repeat a call without checking Action identity, terminal state,\ninput hash, idempotency ownership, and provider outcome.\n\n## Interpret operation kinds\n\nThe two OpenAPI operations are AIP Resources. The remaining 20 operations are\nTools, including record and metadata reads.\n\nThe native AIP caller still submits Resource operations through the Action\npath implemented by the connector host. Kind describes capability semantics;\nit does not expose a caller-selected provider URL.\n\n## Apply approval and idempotency\n\nEvery mutation requires tenant-policy approval. The published validity window\nis 900,000 ms and requires a reason, input snapshot, and policy decision.\n\n| Contract | Read | Mutation |\n|---|---|---|\n| Approval | No | Required |\n| Idempotency key | Optional | Required |\n| Key scope | External account | External account |\n| Collision behavior | Revalidate input hash | Revalidate input hash |\n| Published key TTL | 604800000 ms | 604800000 ms |\n\nThe connector sends a mutation key to Twenty as `Idempotency-Key`. Record\ncreate also derives missing IDs from workspace, key, and record index and\nforces provider upsert.\n\nAn idempotency key identifies one intent. It does not prove that every\nprovider endpoint deduplicates requests or make an uncertain mutation safe to\nrepeat under a new identity.\n\n## Interpret execution and retry\n\nAll 22 operations support synchronous execution and advertise a 120,000 ms\ntimeout hint. None supports connector-managed asynchronous execution,\nstreaming, or cancellation.\n\nAll eight reads advertise retry support. Three mutations also advertise it:\n\n- `record.create`;\n- `record.create_many`;\n- `record.update`.\n\nThose mutations are safe only with the original idempotency key and unchanged\ncanonical input. The remaining eleven mutations advertise unsafe retry.\n\nThe published expected latency, queue delay, and `99.9%` availability value are\ncontract metadata. They are not measured deployment SLOs or qualification\nresults.\n\n## Apply data and side-effect rules\n\nEvery capability declares confidential data, possible personal information,\nand required redaction.\n\nRead operations declare `read` and `external_network`. Create, update, restore,\nmerge, and metadata mutations declare `write` and `external_network`. Delete\noperations declare `delete` and `external_network`.\n\nProvider responses remain provider-shaped. Error projection retains only a\nbounded safe-field allowlist, and webhook metadata results recursively remove\nfields named `secret`.\n\n## Understand compensation and uncertainty\n\nAll 14 mutations declare `rollback_not_supported` and name no compensation\ncapability. The connector also exposes no transaction or reconciliation\noperation.\n\nApproval and idempotency do not make a mutation reversible. Preserve original\nAction, key, provider request identity, output, and receipts whenever a result\nis incomplete or uncertain.\n\nThe connector marks temporary provider failures and many post-dispatch\ntransport or response failures as uncertain for mutations. Recovery must read\nactual provider state before another governed write.\n\n## Understand discovery projection\n\nThe host starts with all 22 operations or a non-empty configured subset. Only\nthat set enters its manifest and invocation dispatcher.\n\nRuntime discovery also depends on tenant, connector admission, route\neligibility, instance lifecycle, artifact identity, and manifest limits. A\nwell-formed capability ID does not authorize a call.\n\nAn operations file is process configuration. Replacing the file without\nrestarting and re-admitting the host does not change the published surface.\n\n## Use the machine snapshot\n\nThe JSON asset contains source identities, aggregate counts, contract defaults,\nand one ordered record for every operation. Each record includes its capability\nID, family, provider method and path template, kind, risk, mutation, approval,\nidempotency, execution, input summary, side effects, data, and compensation.\n\nIts reviewed SHA-256 is:\n\n```text\n35315598e1e392eeeb3d3a0a194d37bfedd86d90da702a7bdc676762318fd465\n```\n\nThe snapshot is a source-derived review artifact. It does not prove registry\nadmission, tenant authorization, artifact qualification, or live provider\ncompatibility.\n\n## Choose the next page\n\n- Use `record-query-and-aggregation.md` for reads and duplicate or grouping\n  input.\n- Use `record-create-update-and-batch-upsert.md` for deterministic upsert and\n  update behavior.\n- Use `record-delete-restore-and-merge.md` for destructive lifecycle changes.\n- Use `workspace-metadata.md` for the twelve supported metadata resource types.\n- Use `openapi-documents.md` for current provider descriptions and drift use.\n- Use the workflow guides for procedures rather than field lookup.\n\n## Related documentation\n\n- [Source-derived capability snapshot](../assets/capabilities.json)\n- [Twenty connector overview](../README.md)\n- [Twenty connector configuration](../reference/configuration.md)\n- [Capabilities and contracts](../../../concepts/capabilities.md)\n- [Approvals and policy](../../../concepts/approvals-and-policy.md)\n",
    "text": "Twenty capabilities\n\nUse this index to choose the Twenty operation family that owns a task and\ninterpret its AIP contract before invocation. The reviewed connector contains\n22 fixed operations across records, workspace metadata, and OpenAPI documents.\n\nThe source-derived machine snapshot owns the ordered inventory. Focused pages\nown input details and task guidance; neither artifact replaces authenticated\ntenant discovery.\n\nCatalogue identity\n\n| Property | Reviewed value |\n\n| AIP source | 97be86e9efedf07ecf1783b03800f683f107fb04 |\n| Provider mapping source | 96a24563674313a3071d359bfccaf33d5e130ab8 |\n| Connector profile | aip.connector.twenty.v1 |\n| Capability prefix | cap:twenty: |\n| Frozen operations | 22 |\n| Reads and mutations | 8 and 14 |\n| Low, high, and critical risk | 8, 9, and 5 |\n| Approval required | 14 |\n| Idempotency key required | 14 |\n| Connector retry support | 11 |\n\nAn operations file can admit any non-empty subset. The full source catalogue\ncount is therefore not the capability count of every running manifest.\n\nRead a capability ID\n\nEvery capability appends its exact operation suffix:\n\ncap:twenty:record.list\n│          │      └─ operation\n│          └──────── resource family\n└─────────────────── connector namespace\n\nOther examples are:\n\ncap:twenty:record.createmany\ncap:twenty:metadata.update\ncap:twenty:openapi.core\n\nDo not derive a capability from a provider route or GraphQL operation. Use the\nadmitted manifest or the source-derived snapshot.\n\nChoose a family\n\n| Family | Focused page | Total | Read | Mutation | Primary use |\n\n| Record query and aggregation | record-query-and-aggregation.md | 4 | 4 | 0 | List, get, detect duplicates, and group records |\n| Record create, update, and batch upsert | record-create-update-and-batch-upsert.md | 4 | 0 | 4 | Create or update standard and custom records |\n| Record delete, restore, and merge | record-delete-restore-and-merge.md | 7 | 0 | 7 | Change record lifecycle or consolidate duplicates |\n| Workspace metadata | workspace-metadata.md | 5 | 2 | 3 | Read and change twelve fixed metadata resource types |\n| OpenAPI documents | openapi-documents.md | 2 | 2 | 0 | Read current core and metadata descriptions |\n| Total |  | 22 | 8 | 14 |  |\n\nSelect the focused page before constructing input. Similar HTTP methods do not\nmake operation schemas or safety contracts interchangeable.\n\nCompare all operations\n\n| Operation | Method | Kind | Risk | Approval | Key | Retry |\n\n| record.list | GET | Tool | Low | No | Optional | Yes |\n| record.get | GET | Tool | Low | No | Optional | Yes |\n| record.findduplicates | POST | Tool | Low | No | Optional | Yes |\n| record.groupby | GET | Tool | Low | No | Optional | Yes |\n| record.create | POST | Tool | High | Yes | Required | Yes |\n| record.createmany | POST | Tool | High | Yes | Required | Yes |\n| record.update | PATCH | Tool | High | Yes | Required | Yes |\n| record.updatemany | PATCH | Tool | High | Yes | Required | No |\n| record.softdelete | DELETE | Tool | High | Yes | Required | No |\n| record.softdeletemany | DELETE | Tool | High | Yes | Required | No |\n| record.destroy | DELETE | Tool | Critical | Yes | Required | No |\n| record.destroymany | DELETE | Tool | Critical | Yes | Required | No |\n| record.restore | PATCH | Tool | High | Yes | Required | No |\n| record.restoremany | PATCH | Tool | High | Yes | Required | No |\n| record.merge | PATCH | Tool | High | Yes | Required | No |\n| metadata.list | GET | Tool | Low | No | Optional | Yes |\n| metadata.get | GET | Tool | Low | No | Optional | Yes |\n| metadata.create | POST | Tool | Critical | Yes | Required | No |\n| metadata.update | PATCH | Tool | Critical | Yes | Required | No |\n| metadata.delete | DELETE | Tool | Critical | Yes | Required | No |\n| openapi.core | GET | Resource | Low | No | Optional | Yes |\n| openapi.metadata | GET | Resource | Low | No | Optional | Yes |\n\nrecord.findduplicates is a read despite its provider POST method.\nrecord.update advertises safe retry with its required idempotency key, while\nthe filtered record.updatemany operation does not.\n\nRetry describes connector contract support. It does not authorize an\napplication to repeat a call without checking Action identity, terminal state,\ninput hash, idempotency ownership, and provider outcome.\n\nInterpret operation kinds\n\nThe two OpenAPI operations are AIP Resources. The remaining 20 operations are\nTools, including record and metadata reads.\n\nThe native AIP caller still submits Resource operations through the Action\npath implemented by the connector host. Kind describes capability semantics;\nit does not expose a caller-selected provider URL.\n\nApply approval and idempotency\n\nEvery mutation requires tenant-policy approval. The published validity window\nis 900,000 ms and requires a reason, input snapshot, and policy decision.\n\n| Contract | Read | Mutation |\n\n| Approval | No | Required |\n| Idempotency key | Optional | Required |\n| Key scope | External account | External account |\n| Collision behavior | Revalidate input hash | Revalidate input hash |\n| Published key TTL | 604800000 ms | 604800000 ms |\n\nThe connector sends a mutation key to Twenty as Idempotency-Key. Record\ncreate also derives missing IDs from workspace, key, and record index and\nforces provider upsert.\n\nAn idempotency key identifies one intent. It does not prove that every\nprovider endpoint deduplicates requests or make an uncertain mutation safe to\nrepeat under a new identity.\n\nInterpret execution and retry\n\nAll 22 operations support synchronous execution and advertise a 120,000 ms\ntimeout hint. None supports connector-managed asynchronous execution,\nstreaming, or cancellation.\n\nAll eight reads advertise retry support. Three mutations also advertise it:\n• record.create;\n• record.createmany;\n• record.update.\n\nThose mutations are safe only with the original idempotency key and unchanged\ncanonical input. The remaining eleven mutations advertise unsafe retry.\n\nThe published expected latency, queue delay, and 99.9% availability value are\ncontract metadata. They are not measured deployment SLOs or qualification\nresults.\n\nApply data and side-effect rules\n\nEvery capability declares confidential data, possible personal information,\nand required redaction.\n\nRead operations declare read and externalnetwork. Create, update, restore,\nmerge, and metadata mutations declare write and externalnetwork. Delete\noperations declare delete and externalnetwork.\n\nProvider responses remain provider-shaped. Error projection retains only a\nbounded safe-field allowlist, and webhook metadata results recursively remove\nfields named secret.\n\nUnderstand compensation and uncertainty\n\nAll 14 mutations declare rollbacknotsupported and name no compensation\ncapability. The connector also exposes no transaction or reconciliation\noperation.\n\nApproval and idempotency do not make a mutation reversible. Preserve original\nAction, key, provider request identity, output, and receipts whenever a result\nis incomplete or uncertain.\n\nThe connector marks temporary provider failures and many post-dispatch\ntransport or response failures as uncertain for mutations. Recovery must read\nactual provider state before another governed write.\n\nUnderstand discovery projection\n\nThe host starts with all 22 operations or a non-empty configured subset. Only\nthat set enters its manifest and invocation dispatcher.\n\nRuntime discovery also depends on tenant, connector admission, route\neligibility, instance lifecycle, artifact identity, and manifest limits. A\nwell-formed capability ID does not authorize a call.\n\nAn operations file is process configuration. Replacing the file without\nrestarting and re-admitting the host does not change the published surface.\n\nUse the machine snapshot\n\nThe JSON asset contains source identities, aggregate counts, contract defaults,\nand one ordered record for every operation. Each record includes its capability\nID, family, provider method and path template, kind, risk, mutation, approval,\nidempotency, execution, input summary, side effects, data, and compensation.\n\nIts reviewed SHA-256 is:\n\n35315598e1e392eeeb3d3a0a194d37bfedd86d90da702a7bdc676762318fd465\n\nThe snapshot is a source-derived review artifact. It does not prove registry\nadmission, tenant authorization, artifact qualification, or live provider\ncompatibility.\n\nChoose the next page\n• Use record-query-and-aggregation.md for reads and duplicate or grouping\n  input.\n• Use record-create-update-and-batch-upsert.md for deterministic upsert and\n  update behavior.\n• Use record-delete-restore-and-merge.md for destructive lifecycle changes.\n• Use workspace-metadata.md for the twelve supported metadata resource types.\n• Use openapi-documents.md for current provider descriptions and drift use.\n• Use the workflow guides for procedures rather than field lookup.\n\nRelated documentation\n• Source-derived capability snapshot (../assets/capabilities.json)\n• Twenty connector overview (../README.md)\n• Twenty connector configuration (../reference/configuration.md)\n• Capabilities and contracts (../../../concepts/capabilities.md)\n• Approvals and policy (../../../concepts/approvals-and-policy.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "a59f3dd8f611c2e8c0e750172a20cfb1c085b52eb69f4f269531b6066e5757c2"
  }
}