openapi: 3.1.0 info: title: API Reference subpackage_bulkSync subpackage_entities API version: 1.0.0 servers: - url: https://app.polytomic.com tags: - name: subpackage_entities paths: /api/entities/{id}: get: operationId: get summary: Get Entity description: "Returns a resolved entity by ID.\n\nLooks up a UUID within the caller's current organization and returns the\nresource type plus enough context to fetch the canonical resource.\n\nThis endpoint is useful when you have an execution, sync, model, connection,\norganization, or user UUID and need to determine what it refers to.\n\nThe response always includes:\n\n- `id`: the UUID that was resolved.\n- `type`: the resolved entity type.\n- `canonical_path`: the canonical REST path for the resolved resource.\n\nThe response may also include:\n\n- `relationships`: parent resources needed to address nested resources.\n- `context`: lightweight additional context, such as bulk sync `schema_ids`.\n\nFor the normal user-scoped endpoint, `organization_id` is omitted from the\nresponse.\n\nSupported `type` values currently include:\n\n- `organization`\n- `user`\n- `connection`\n- `model`\n- `sync`\n- `sync_execution`\n- `bulk_sync`\n- `bulk_sync_execution`\n\nExamples:\n\n- A model sync execution resolves to a `sync_execution` and includes a `sync`\n relationship.\n- A bulk sync execution resolves to a `bulk_sync_execution`, includes a\n `bulk_sync` relationship, and may include `context.schema_ids`.\n\nIf the UUID does not exist, or exists outside the caller's scoped\norganization, the endpoint returns `404`." tags: - subpackage_entities parameters: - name: id in: path description: UUID of the entity to resolve. required: true schema: type: string format: uuid - name: Authorization in: header description: Bearer user API key required: true schema: type: string - name: X-Polytomic-Version in: header required: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EntityResponseEnvelope' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiError' /api/organizations/entities/{id}: get: operationId: get-for-partner summary: Get Partner Entity description: "Returns a resolved entity by ID within a partner organization scope.\n\nLooks up a UUID across organizations using partner authentication and returns\nthe resource type plus enough context to fetch the canonical resource.\n\nThis endpoint is intended for cross-organization partner workflows where the\ncaller has an arbitrary UUID and needs to discover both the resource type and\nthe organization it belongs to.\n\nThe response always includes:\n\n- `id`: the UUID that was resolved.\n- `type`: the resolved entity type.\n- `canonical_path`: the canonical REST path for the resolved resource.\n- `organization_id`: the organization that owns the resolved resource.\n\nThe response may also include:\n\n- `relationships`: parent resources needed to address nested resources.\n- `context`: lightweight additional context, such as bulk sync `schema_ids`.\n\nSupported `type` values currently include:\n\n- `organization`\n- `user`\n- `connection`\n- `model`\n- `sync`\n- `sync_execution`\n- `bulk_sync`\n- `bulk_sync_execution`\n\nExamples:\n\n- A model sync execution resolves to a `sync_execution` and includes a `sync`\n relationship.\n- A bulk sync execution resolves to a `bulk_sync_execution`, includes a\n `bulk_sync` relationship, and may include `context.schema_ids`.\n\nIf the UUID does not exist, the endpoint returns `404`." tags: - subpackage_entities parameters: - name: id in: path description: UUID of the entity to resolve. required: true schema: type: string format: uuid - name: Authorization in: header description: Bearer partner API key required: true schema: type: string - name: X-Polytomic-Version in: header required: false schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EntityResponseEnvelope' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiError' components: schemas: EntityResponse: type: object properties: canonical_path: type: string description: Canonical REST path for the resolved resource, suitable for fetching it directly. context: type: object additionalProperties: description: Any type description: Lightweight additional context about the resolved entity, such as bulk sync schema_ids. id: type: string format: uuid description: UUID that was resolved. organization_id: type: string format: uuid description: Organization that owns the resolved resource. Omitted from responses on the user-scoped endpoint. relationships: type: object additionalProperties: $ref: '#/components/schemas/EntityRelationship' description: Parent resources needed to address nested resources, keyed by relationship name (e.g. "sync", "bulk_sync"). type: type: string description: 'Resolved entity type. One of: organization, user, connection, model, sync, sync_execution, bulk_sync, bulk_sync_execution.' title: EntityResponse ApiError: type: object properties: key: type: string message: type: string metadata: type: object additionalProperties: description: Any type status: type: integer title: ApiError EntityRelationship: type: object properties: id: type: string format: uuid description: UUID of the related resource. path: type: string description: Canonical REST path of the related resource. title: EntityRelationship EntityResponseEnvelope: type: object properties: data: $ref: '#/components/schemas/EntityResponse' title: EntityResponseEnvelope securitySchemes: bearerUserAPIKey: type: http scheme: bearer description: Bearer user API key orgScopedAPIKey: type: http scheme: basic description: Basic organization-scoped API key bearerPartnerKey: type: http scheme: bearer description: Bearer partner API key