{"openapi":"3.1.0","info":{"title":"RightBrain API","description":"\nThe RightBrain API provides programmatic access to AI-powered task execution.\n","version":"v1","x-logo":{"url":"https://rightbrain.ai/logo.png","altText":"RightBrain AI Logo"},"x-api-version":"v1","x-api-version-path":"/api/v1/","x-docs-url":"https://docs.rightbrain.ai","x-support-email":"support@rightbrain.ai"},"paths":{"/org/{org_id}/iam/members":{"get":{"tags":["Organizations"],"summary":"IAM - List Organization Members","description":"Lists all members that have been granted direct access to the organization.","operationId":"organization_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:view","organization:view_members"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."}],"responses":{"200":{"description":"Successfully retrieved Organization members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Organization Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/iam/members/{member}":{"get":{"tags":["Organizations"],"summary":"IAM - Lookup Organization Member","description":"Retrieve a specific member that has been granted direct access to the organization.","operationId":"organization_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:view","organization:view_members"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}}],"responses":{"200":{"description":"Organization member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Organization Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Organizations"],"summary":"IAM - Update Organization Member","description":"Update the roles that a member holds on the organization.","operationId":"organization_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Organization member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Organization Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Organization Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/iam/test":{"post":{"tags":["Organizations"],"summary":"IAM - Test Organization Permissions","description":"Test the permissions that the caller (or another subject) holds on the organization.","operationId":"organization_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Organization permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Organization Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Organization Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org":{"get":{"tags":["Organizations"],"summary":"List Organizations","operationId":"listOrganizations","security":[{"HTTPBearer":[]}],"parameters":[{"name":"membership","in":"query","required":false,"description":"Filter organizations by membership status.\n\n**Values:**\n- `active` (default) - Organizations you belong to\n- `joinable` - Organizations you can request to join\n- `joinable_by_domain` - Organizations matching your email domain\n- `joinable_by_invite` - Organizations you have pending invites to","schema":{"type":"string","enum":["active","joinable","joinable_by_domain","joinable_by_invite"],"default":"active"},"example":"active"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"Pagination cursor for the next page of results"},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"Maximum number of organizations to return per page"}],"responses":{"200":{"description":"Successfully retrieved organizations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_Org_"},"example":{"results":[{"id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Meridian Freight Logistics","contact_email":"ops@meridianfreight.com","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/organization/019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01/base.png","public_metadata":{},"low_credit_alerts":true,"usage_based_pricing_enabled":false,"plan":"teams","plan_status":"active","plan_interval":"monthly","auto_topup_config":{"enabled":false},"account":{"id":"019a2f10-8a2c-7e43-8e97-1c9d4e7b6f0a","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","credits":48000,"modified":"2026-07-15T09:00:00Z"}},{"id":"019a2f10-8f1d-7e4a-8fa8-1c9d4e7b6f0b","name":"Meridian Sandbox","contact_email":"ops@meridianfreight.com","public_metadata":{},"low_credit_alerts":false,"usage_based_pricing_enabled":false,"plan":"trial","plan_status":"active","trial_ends_at":"2026-08-19T00:00:00Z","auto_topup_config":{},"account":{"id":"019a2f10-8f2e-7e4b-90b9-1c9d4e7b6f0c","org_id":"019a2f10-8f1d-7e4a-8fa8-1c9d4e7b6f0b","credits":500,"modified":"2026-07-01T00:00:00Z"}}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve organizations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List organizations based on the user's relationship to them.\n\nUse the `membership` parameter to filter organizations by your access level:\n- **active**: Organizations you are a member of (default)\n- **joinable**: Organizations you can request to join\n- **joinable_by_domain**: Organizations that accept members from your email domain\n- **joinable_by_invite**: Organizations you have pending invites to\n\nThis endpoint is useful for:\n- Displaying the user's current organizations\n- Showing organizations the user can join\n- Building organization switching interfaces"},"post":{"tags":["Organizations"],"summary":"Create Organization","operationId":"createOrganization","security":[{"HTTPBearer":[]},{"HTTPBearer":["system:organizations_create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgCreate"},"examples":{"basic":{"summary":"Basic Organization","value":{"name":"Meridian Freight Logistics","contact_email":"ops@meridianfreight.com"}},"second_org":{"summary":"Another Organization","value":{"name":"Anchor Bay Freight","contact_email":"admin@anchorbayfreight.com"}}}}}},"responses":{"200":{"description":"Organization created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"},"examples":{"Basic Organization":{"summary":"Basic Organization","value":{"id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Meridian Freight Logistics","contact_email":"ops@meridianfreight.com","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/organization/019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01/base.png","public_metadata":{},"low_credit_alerts":false,"usage_based_pricing_enabled":false,"plan":"trial","plan_status":"active","trial_ends_at":"2026-08-24T00:00:00Z","auto_topup_config":{"enabled":false},"account":{"id":"019a2f10-8a2c-7e43-8e97-1c9d4e7b6f0a","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","credits":0,"modified":"2026-07-25T00:00:00Z"}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid organization"}}},"description":"Bad Request - Invalid organization\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createorganization"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"409":{"description":"Conflict - Organization name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Organization name already exists"}}}},"500":{"description":"Internal Server Error - Failed to create organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a new organization"}},"/org/{org_id}":{"post":{"tags":["Organizations"],"summary":"Update Organization","operationId":"updateOrganization","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgUpdate"},"examples":{"update_contact_email":{"summary":"Update Contact Email","value":{"contact_email":"billing@meridianfreight.com"}},"enable_low_credit_alerts":{"summary":"Enable Low Credit Alerts","value":{"low_credit_alerts":true}}}}}},"responses":{"200":{"description":"Organization updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"},"examples":{"Update Contact Email":{"summary":"Update Contact Email","value":{"id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Meridian Freight Logistics","contact_email":"billing@meridianfreight.com","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/organization/019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01/base.png","public_metadata":{},"low_credit_alerts":true,"usage_based_pricing_enabled":false,"plan":"teams","plan_status":"active","plan_interval":"monthly","auto_topup_config":{"enabled":false},"account":{"id":"019a2f10-8a2c-7e43-8e97-1c9d4e7b6f0a","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","credits":48000,"modified":"2026-07-15T09:00:00Z"}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid organization"}}},"description":"Bad Request - Invalid organization\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateorganization"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to update organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update organization details"},"get":{"tags":["Organizations"],"summary":"Get Organization","operationId":"getOrganization","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"responses":{"200":{"description":"Organization details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"},"example":{"id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Meridian Freight Logistics","contact_email":"ops@meridianfreight.com","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/organization/019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01/base.png","public_metadata":{},"low_credit_alerts":true,"usage_based_pricing_enabled":false,"plan":"teams","plan_status":"active","plan_interval":"monthly","auto_topup_config":{"enabled":false},"account":{"id":"019a2f10-8a2c-7e43-8e97-1c9d4e7b6f0a","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","credits":48000,"modified":"2026-07-15T09:00:00Z"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getorganization"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Get organization details by ID"}},"/org/{org_id}/join":{"post":{"tags":["Organizations"],"summary":"Join Organization","operationId":"joinOrganization","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:join"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"responses":{"200":{"description":"Organization joined","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:019a2f10-9a4f-7e45-8e86-1c9d4e7b6f11","roles":["editor"],"name":"Carlos Reyes","total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Invalid invite code"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Joinorganization"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have join permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"join"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Invite not found or expired"},"409":{"description":"Already a member"},"500":{"description":"Internal Server Error - Failed to join organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Join an organization using an invite code"}},"/org/{org_id}/invite":{"get":{"tags":["Organizations"],"summary":"List Organization Invites","operationId":"listOrganizationInvites","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:view_members"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"show","in":"query","required":false,"description":"Filter invites by acceptance status.\n\n**Values:**\n- `pending` (default) - Invites not yet accepted\n- `accepted` - Invites that have been accepted\n- `all` - All invites regardless of status","schema":{"type":"string","enum":["all","pending","accepted"],"default":"pending"},"example":"pending"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"Pagination cursor for the next page of results"},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"Maximum number of invites to return per page"}],"responses":{"200":{"description":"Successfully retrieved invites","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_OrganizationInvite_"},"example":{"results":[{"id":"019a2f10-9d72-7e48-91b9-1c9d4e7b6f14","email_address":"carlos.reyes@meridianfreight.com","roles":["editor"],"project_roles":{"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02":["task_creator"]}},{"id":"019a2f10-9e83-7e49-92ca-1c9d4e7b6f15","email_address":"jamie.ortiz@meridianfreight.com","roles":["viewer"]}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listorganizationinvites"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view_members permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view_members"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list invites","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List invites for the organization with optional filtering by\nstatus.\n\nUse the `show` parameter to filter invites:\n- **pending**: Only unaccepted invites (default)\n- **accepted**: Only accepted invites\n- **all**: All invites regardless of status\n\nThis endpoint is useful for:\n- Managing pending invitations\n- Auditing who has accepted invites\n- Resending or revoking invites"},"post":{"tags":["Organizations"],"summary":"Create Organization Invite","operationId":"createOrganizationInvite","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:add_member"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgInviteWithProjectRoles"},"examples":{"org_role_only":{"summary":"Organization role only","value":{"email_address":"carlos.reyes@meridianfreight.com","roles":["editor"]}},"with_project_roles":{"summary":"With per-project roles","description":"Granting `editor` additionally requires `add_editor` on the organization - see the 403 below.","value":{"email_address":"carlos.reyes@meridianfreight.com","roles":["editor"],"project_roles":{"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02":["task_creator"]}}}}}}},"responses":{"200":{"description":"Invite created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationInvite"},"examples":{"Organization role only":{"summary":"Organization role only","value":{"id":"019a2f10-9d72-7e48-91b9-1c9d4e7b6f14","email_address":"carlos.reyes@meridianfreight.com","roles":["editor"],"project_roles":{"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02":["task_creator"]}}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/OrganizationInviteAlreadyExistsErrorResponse"},{"$ref":"#/components/schemas/OrganizationMemberAlreadyExistsErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Createorganizationinvite"},"example":{"detail":{"reason":"ORGANIZATION_INVITE_ALREADY_EXISTS","message":"Invite for email address [carlos.reyes@example.com] already exists in organization [0190a234-5678-9abc-def0-123456789abc]","organizationInviteAlreadyExistsError":{"organization_id":"0190a234-5678-9abc-def0-123456789abc","email_address":"carlos.reyes@example.com"}}}}},"description":"Bad Request - the invite could not be created"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createorganizationinvite"},"examples":{"cannot_invite":{"summary":"Cannot invite members","description":"The route-level check. Requires `add_member`, which resolves to `organization:edit` - an owner or editor.","value":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have add_member permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"add_member"}}}},"cannot_grant_role":{"summary":"Cannot grant the requested role","description":"The secondary check. Sending `roles: [\"editor\"]` additionally requires `add_editor` (owners only); `roles: [\"owner\"]` requires `add_owner`, which in `spicedb/schema.zed` resolves only through `system->organizations_edit` - so an organization owner cannot invite another owner through this endpoint.","value":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have add_editor permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"add_editor"}}}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"409":{"description":"User already invited"},"500":{"description":"Internal Server Error - Failed to create invite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create an invite to join the organization.\n\n`roles` are organization-level roles; `project_roles` maps a project id to the\nroles the invitee should hold in that project. Both are optional — an invite with\nneither grants organization membership only."}},"/org/{org_id}/invite/{org_invite_id}":{"delete":{"tags":["Organizations"],"summary":"Delete Organization Invite","operationId":"deleteOrganizationInvite","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:remove_member"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"org_invite_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Invite Id"},"description":"The invite ID to delete"}],"responses":{"204":{"description":"Invite cancelled"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deleteorganizationinvite"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have remove_member permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"remove_member"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Invite not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find invite [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"invite","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to cancel invite","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Cancel a pending invite"}},"/org/{org_id}/domains":{"get":{"tags":["Organizations"],"summary":"List Organization Domains","operationId":"listOrganizationDomains","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"responses":{"200":{"description":"Successfully retrieved domains","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_OrganizationDomain_"},"example":{"results":[{"id":"019a2f10-9b50-7e46-8f97-1c9d4e7b6f12","domain":"meridianfreight.com","status":"verified"},{"id":"019a2f10-9c61-7e47-90a8-1c9d4e7b6f13","domain":"meridianfreight.co.uk","status":"unverified"}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listorganizationdomains"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list domains","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List verified domains for the organization"},"post":{"tags":["Organizations"],"summary":"Add Organization Domain","operationId":"createOrganizationDomain","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDomainCreate"},"examples":{"add_domain":{"summary":"Add Domain","value":{"domain":"meridianfreight.co.uk"}}}}}},"responses":{"200":{"description":"Domain created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDomain"},"examples":{"Add Domain":{"summary":"Add Domain","value":{"id":"019a2f10-9c61-7e47-90a8-1c9d4e7b6f13","domain":"meridianfreight.co.uk","status":"unverified"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid domain"}}},"description":"Bad Request - Invalid domain\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createorganizationdomain"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"409":{"description":"Domain already exists"},"500":{"description":"Internal Server Error - Failed to add domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Add a domain to the organization"}},"/org/{org_id}/domains/{domain_id}":{"delete":{"tags":["Organizations"],"summary":"Delete Organization Domain","operationId":"deleteOrganizationDomain","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"domain_id","in":"path","required":true,"schema":{"type":"string","title":"Domain Id"},"description":"The domain ID to remove"}],"responses":{"200":{"description":"Domain removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationDomain"},"example":{"id":"019a2f10-9c61-7e47-90a8-1c9d4e7b6f13","domain":"meridianfreight.co.uk","status":"unverified"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deleteorganizationdomain"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Domain not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find domain [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"domain","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to remove domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Remove a domain from the organization"}},"/org/{org_id}/avatar":{"post":{"tags":["Organizations"],"summary":"Update Organization Avatar","operationId":"updateOrgAvatar","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_updateOrgAvatar","type":"object","properties":{"file":{"type":"string","format":"binary","description":"Avatar image file (JPEG, PNG, GIF)"}},"required":["file"]},"examples":{"avatar_upload":{"summary":"Avatar Upload","value":{"file":"Binary image data"}}}}}},"responses":{"200":{"description":"Avatar updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Org"},"examples":{"Avatar Upload":{"summary":"Avatar Upload","value":{"id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Meridian Freight Logistics","contact_email":"ops@meridianfreight.com","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/organization/019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01/base.png","public_metadata":{},"low_credit_alerts":true,"usage_based_pricing_enabled":false,"plan":"teams","plan_status":"active","plan_interval":"monthly","auto_topup_config":{"enabled":false},"account":{"id":"019a2f10-8a2c-7e43-8e97-1c9d4e7b6f0a","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","credits":48000,"modified":"2026-07-15T09:00:00Z"}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Invalid image"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateorgavatar"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to update avatar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update organization avatar image"}},"/partner":{"get":{"tags":["Partners"],"summary":"List Partners","operationId":"listPartners","security":[{"HTTPBearer":[]},{"HTTPBearer":["system:partners_view"]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."}],"responses":{"200":{"description":"Successfully retrieved Partners","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_Partner_"},"example":{"results":[{"id":"019c1f20-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Northstar Consulting","description":"Implementation and enablement partner for enterprise AI teams.","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/partner/019c1f20-8a1c-7e42-9b53-1c9d4e7b6f01/base.png","created":"2026-08-11T09:00:00Z","modified":"2026-08-11T09:00:00Z"}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listpartners"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have partners_view permission on system [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"system","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"partners_view"}}}}},"description":"Forbidden - Insufficient permissions for system\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The system belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list Partners","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List Partners visible to platform administrators and support staff."},"post":{"tags":["Partners"],"summary":"Create Partner","operationId":"createPartner","security":[{"HTTPBearer":[]},{"HTTPBearer":["system:partners_create"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerCreate"},"example":{"name":"Northstar Consulting","description":"Implementation and enablement partner for enterprise AI teams."}}}},"responses":{"200":{"description":"Partner details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"},"example":{"id":"019c1f20-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Northstar Consulting","description":"Implementation and enablement partner for enterprise AI teams.","avatar_url":null,"created":"2026-08-11T09:00:00Z","modified":"2026-08-11T09:00:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createpartner"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have partners_create permission on system [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"system","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"partners_create"}}}}},"description":"Forbidden - Insufficient permissions for system\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The system belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to create Partner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a Partner."}},"/partner/{partner_id}":{"get":{"tags":["Partners"],"summary":"Get Partner","operationId":"getPartner","security":[{"HTTPBearer":[]},{"HTTPBearer":["system:partners_view"]}],"parameters":[{"name":"partner_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Partner Id"},"description":"The partner ID"}],"responses":{"200":{"description":"Partner details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"},"example":{"id":"019c1f20-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Northstar Consulting","description":"Implementation and enablement partner for enterprise AI teams.","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/partner/019c1f20-8a1c-7e42-9b53-1c9d4e7b6f01/base.png","created":"2026-08-11T09:00:00Z","modified":"2026-08-11T09:00:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getpartner"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have partners_view permission on system [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"system","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"partners_view"}}}}},"description":"Forbidden - Insufficient permissions for system\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The system belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Partner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find partner [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"partner","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve Partner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Get a Partner by ID."},"post":{"tags":["Partners"],"summary":"Update Partner","operationId":"updatePartner","security":[{"HTTPBearer":[]},{"HTTPBearer":["system:partners_edit"]}],"parameters":[{"name":"partner_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Partner Id"},"description":"The partner ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerUpdate"},"example":{"name":"Northstar Consulting Group","description":"Enterprise implementation and enablement partner."}}}},"responses":{"200":{"description":"Partner updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"},"example":{"id":"019c1f20-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Northstar Consulting","description":"Implementation and enablement partner for enterprise AI teams.","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/partner/019c1f20-8a1c-7e42-9b53-1c9d4e7b6f01/base.png","created":"2026-08-11T09:00:00Z","modified":"2026-08-11T09:00:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatepartner"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have partners_edit permission on system [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"system","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"partners_edit"}}}}},"description":"Forbidden - Insufficient permissions for system\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The system belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Partner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find partner [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"partner","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to update Partner","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update a Partner's name or description."}},"/partner/{partner_id}/avatar":{"post":{"tags":["Partners"],"summary":"Update Partner Avatar","operationId":"updatePartnerAvatar","security":[{"HTTPBearer":[]},{"HTTPBearer":["system:partners_edit"]}],"parameters":[{"name":"partner_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Partner Id"},"description":"The partner ID"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_updatePartnerAvatar","type":"object","properties":{"file":{"type":"string","format":"binary","description":"Logo image file (JPEG or PNG)"}},"required":["file"]},"examples":{"logo_upload":{"summary":"Logo Upload","value":{"file":"Binary image data"}}}}}},"responses":{"200":{"description":"Partner updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Partner"},"examples":{"Logo Upload":{"summary":"Logo Upload","value":{"id":"019c1f20-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Northstar Consulting","description":"Implementation and enablement partner for enterprise AI teams.","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/partner/019c1f20-8a1c-7e42-9b53-1c9d4e7b6f01/base.png","created":"2026-08-11T09:00:00Z","modified":"2026-08-11T09:00:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Invalid image"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatepartneravatar"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have partners_edit permission on system [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"system","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"partners_edit"}}}}},"description":"Forbidden - Insufficient permissions for system\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The system belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Partner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find partner [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"partner","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to update Partner avatar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Upload a Partner logo image."}},"/partner/{partner_id}/organizations":{"get":{"tags":["Partners"],"summary":"List Partner Organizations","operationId":"listPartnerOrganizations","security":[{"HTTPBearer":[]},{"HTTPBearer":["system:partners_view"]}],"parameters":[{"name":"partner_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Partner Id"},"description":"The partner ID"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."}],"responses":{"200":{"description":"Successfully retrieved Partner Organizations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_PartnerOrganizationSummary_"},"example":{"results":[{"id":"019c1f20-8b2d-7e43-9c64-1c9d4e7b6f02","name":"Meridian Freight Logistics","created":"2026-07-15T09:00:00Z"}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listpartnerorganizations"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have partners_view permission on system [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"system","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"partners_view"}}}}},"description":"Forbidden - Insufficient permissions for system\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The system belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Partner not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find partner [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"partner","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to list Partner Organizations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List the Organizations currently linked to a Partner."}},"/partner/{partner_id}/organizations/{org_id}":{"post":{"tags":["Partners"],"summary":"Link Partner Organization","operationId":"linkPartnerOrganization","security":[{"HTTPBearer":[]},{"HTTPBearer":["system:partners_edit"]}],"parameters":[{"name":"partner_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Partner Id"},"description":"The partner ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"responses":{"200":{"description":"Partner Organization details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerOrganizationSummary"},"example":{"id":"019c1f20-8b2d-7e43-9c64-1c9d4e7b6f02","name":"Meridian Freight Logistics","created":"2026-07-15T09:00:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Linkpartnerorganization"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have partners_edit permission on system [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"system","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"partners_edit"}}}}},"description":"Forbidden - Insufficient permissions for system\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The system belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"The Partner or Organization does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"partner_not_found":{"summary":"Partner not found","value":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find partner [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"partner","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}},"organization_not_found":{"summary":"Organization not found","value":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"organization","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}}},"409":{"description":"Conflict - the Organization is linked to another Partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Organization is linked to another Partner"}}}},"500":{"description":"Internal Server Error - Failed to link Partner Organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Link an unassigned Organization to a Partner."},"delete":{"tags":["Partners"],"summary":"Unlink Partner Organization","operationId":"unlinkPartnerOrganization","security":[{"HTTPBearer":[]},{"HTTPBearer":["system:partners_edit"]}],"parameters":[{"name":"partner_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Partner Id"},"description":"The partner ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"responses":{"204":{"description":"Partner Organization link deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Unlinkpartnerorganization"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have partners_edit permission on system [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"system","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"partners_edit"}}}}},"description":"Forbidden - Insufficient permissions for system\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The system belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"The Partner or Organization does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"partner_not_found":{"summary":"Partner not found","value":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find partner [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"partner","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}},"organization_not_found":{"summary":"Organization not found","value":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"organization","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}}},"409":{"description":"Conflict - the Organization is linked to another Partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Organization is linked to another Partner"}}}},"500":{"description":"Internal Server Error - Failed to unlink Partner Organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Remove an Organization's link to a Partner."}},"/org/{org_id}/model/exclude/by-id":{"post":{"tags":["Model Availability Rules"],"summary":"Exclude Specific Model from Organization","operationId":"excludeModelByIdFromOrg","security":[{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExcludeModelByIdRequest"},"examples":{"exclude_model":{"summary":"Exclude a model with an audit reason","value":{"model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","reason":"Restricted by model governance policy"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelExclusionMutationResponse"},"examples":{"Exclude a model with an audit reason":{"summary":"Exclude a model with an audit reason","value":{"status":"excluded","rule_type":"model_id","model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Excludemodelbyidfromorg"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"Exclude one model across the organization.\nRequires `organization:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/model/exclude/by-provider":{"post":{"tags":["Model Availability Rules"],"summary":"Exclude Provider from Organization","operationId":"excludeModelByProviderFromOrg","security":[{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExcludeModelByProviderRequest"},"examples":{"exclude_provider":{"summary":"Exclude all models from a provider","value":{"provider":"OpenAI","reason":"Provider is not approved for this workload"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelExclusionMutationResponse"},"examples":{"Exclude all models from a provider":{"summary":"Exclude all models from a provider","value":{"status":"excluded","rule_type":"provider","provider":"OpenAI"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Excludemodelbyproviderfromorg"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"Exclude all models supplied by a provider across the organization.\nRequires `organization:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/model/exclude/by-vendor":{"post":{"tags":["Model Availability Rules"],"summary":"Exclude Vendor from Organization","operationId":"excludeModelByVendorFromOrg","security":[{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExcludeModelByVendorRequest"},"examples":{"exclude_vendor":{"summary":"Exclude all models served by a vendor","value":{"vendor":"openai","reason":"Temporary vendor restriction"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelExclusionMutationResponse"},"examples":{"Exclude all models served by a vendor":{"summary":"Exclude all models served by a vendor","value":{"status":"excluded","rule_type":"vendor","vendor":"openai"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Excludemodelbyvendorfromorg"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"Exclude all models served by a vendor across the organization.\nRequires `organization:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/model/exclude/{rule_type}/{value}":{"delete":{"tags":["Model Availability Rules"],"summary":"Remove Organization Model Exclusion","operationId":"removeModelExclusionFromOrg","security":[{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"rule_type","in":"path","required":true,"schema":{"enum":["model_id","provider","vendor"],"type":"string","title":"Rule Type"},"description":"The exclusion selector type"},{"name":"value","in":"path","required":true,"schema":{"type":"string","title":"Value"},"description":"The selector value to remove"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelExclusionRemovalResponse"},"example":{"status":"removed","rule_type":"model_id","value":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Removemodelexclusionfromorg"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"Remove an organization rule and widen model availability. \nRequires `organization:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/model/exclusions":{"get":{"tags":["Model Availability Rules"],"summary":"List Organization Model Exclusions","operationId":"listModelExclusionsForOrg","security":[{"HTTPBearer":["organization:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ModelExclusionRuleResponse"},"title":"Response Listmodelexclusionsfororg"},"example":[{"rule_type":"model_id","model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","excluded_at":"2026-07-27T18:49:37.598898Z","excluded_by_user_id":"2f5f236c-bb4a-4d90-945c-4244f34187a2","reason":"Restricted by model governance policy","affected_model_count":1,"affected_models":["GPT 4o Mini"]}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listmodelexclusionsfororg"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"List organization rules with their impact on active models. **Note**: this returns a plain array, not a paginated response. \nRequires `organization:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/project/{project_id}/model/exclude/by-id":{"post":{"tags":["Model Availability Rules"],"summary":"Exclude Specific Model from Project","operationId":"excludeModelByIdFromProject","security":[{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExcludeModelByIdRequest"},"examples":{"exclude_model":{"summary":"Exclude a model with an audit reason","value":{"model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","reason":"Restricted by model governance policy"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelExclusionMutationResponse"},"examples":{"Exclude a model with an audit reason":{"summary":"Exclude a model with an audit reason","value":{"status":"excluded","rule_type":"model_id","model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Excludemodelbyidfromproject"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"Exclude one model from the project. \nRequires `project:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/project/{project_id}/model/exclude/by-provider":{"post":{"tags":["Model Availability Rules"],"summary":"Exclude Provider from Project","operationId":"excludeModelByProviderFromProject","security":[{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExcludeModelByProviderRequest"},"examples":{"exclude_provider":{"summary":"Exclude all models from a provider","value":{"provider":"OpenAI","reason":"Provider is not approved for this workload"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelExclusionMutationResponse"},"examples":{"Exclude all models from a provider":{"summary":"Exclude all models from a provider","value":{"status":"excluded","rule_type":"provider","provider":"OpenAI"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Excludemodelbyproviderfromproject"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"Exclude all models supplied by a provider from the project. \nRequires `project:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/project/{project_id}/model/exclude/by-vendor":{"post":{"tags":["Model Availability Rules"],"summary":"Exclude Vendor from Project","operationId":"excludeModelByVendorFromProject","security":[{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExcludeModelByVendorRequest"},"examples":{"exclude_vendor":{"summary":"Exclude all models served by a vendor","value":{"vendor":"openai","reason":"Temporary vendor restriction"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelExclusionMutationResponse"},"examples":{"Exclude all models served by a vendor":{"summary":"Exclude all models served by a vendor","value":{"status":"excluded","rule_type":"vendor","vendor":"openai"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Excludemodelbyvendorfromproject"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"Exclude all models served by a vendor from the project. \nRequires `project:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/project/{project_id}/model/exclude/{rule_type}/{value}":{"delete":{"tags":["Model Availability Rules"],"summary":"Remove Project Model Exclusion","operationId":"removeModelExclusionFromProject","security":[{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"rule_type","in":"path","required":true,"schema":{"enum":["model_id","provider","vendor"],"type":"string","title":"Rule Type"},"description":"The exclusion selector type"},{"name":"value","in":"path","required":true,"schema":{"type":"string","title":"Value"},"description":"The selector value to remove"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelExclusionRemovalResponse"},"example":{"status":"removed","rule_type":"model_id","value":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Removemodelexclusionfromproject"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"Remove a project rule without changing inherited rules. \nRequires `project:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/project/{project_id}/model/exclusions":{"get":{"tags":["Model Availability Rules"],"summary":"List Project Model Exclusions","operationId":"listModelExclusionsForProject","security":[{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ModelExclusionRuleResponse"},"title":"Response Listmodelexclusionsforproject"},"example":[{"rule_type":"model_id","model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","excluded_at":"2026-07-27T18:49:37.598898Z","excluded_by_user_id":"2f5f236c-bb4a-4d90-945c-4244f34187a2","reason":"Restricted by model governance policy","affected_model_count":1,"affected_models":["GPT 4o Mini"]}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listmodelexclusionsforproject"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"List project-owned rules with their impact on active models. **Note**: this returns a plain array, not a paginated response. \nRequires `project:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/org/{org_id}/project/{project_id}/model/exclusions/effective":{"get":{"tags":["Model Availability Rules"],"summary":"Get Effective Project Model Exclusions","operationId":"getEffectiveModelExclusions","security":[{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EffectiveModelExclusionsResponse"},"example":{"organization_rules":[],"project_rules":[{"rule_type":"model_id","model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","excluded_at":"2026-07-27T18:49:37.598898Z","excluded_by_user_id":"2f5f236c-bb4a-4d90-945c-4244f34187a2","reason":"Restricted by model governance policy","affected_model_count":1,"affected_models":["GPT 4o Mini"]}],"total_excluded_models":1,"available_model_count":61}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Geteffectivemodelexclusions"}}},"description":"Forbidden"},"404":{"description":"No matching exclusion rule found for the given selector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No matching model_id exclusion rule found"}}}},"409":{"description":"That model/provider/vendor is already excluded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' is already excluded"}}}},"422":{"description":"The selector doesn't match any model, or excluding it would leave an affected project without an active model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No model matches model_id 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41'"}}}}},"description":"List organization and project rules and their combined active-model impact. \nRequires `project:edit` access. Organization exclusions are inherited by every\nproject and cannot be overridden at project scope. Provider and vendor rules also\napply to future matching models. A request is rejected if it would leave any\naffected project without at least one active model.\n"}},"/user":{"get":{"tags":["Users"],"summary":"Get User Profile","description":"Get the current user's profile.\n\nReturns:\n- Email and name\n- Bio and job role\n- Avatar URL\n- Newsletter subscription status\n- Onboarding status","operationId":"getCurrentUser","responses":{"200":{"description":"User details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"example":{"email":"jamie.ortiz@meridianfreight.com","name":"Jamie Ortiz","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/user/019a2f10-9a4f-7e45-8e86-1c9d4e7b6f11/base.png","subscribed_to_newsletter":true,"job_role":"engineer","id":"019a2f10-9a4f-7e45-8e86-1c9d4e7b6f11","is_onboarding":false}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["Users"],"summary":"Update User Profile","description":"Update the current user's own profile.\n\nOnly fields present in the request are changed; omitted fields keep their\ncurrent values. This endpoint always updates the authenticated user - there\nis no request body field to target a different user, and it never creates a\nnew user record.","operationId":"updateCurrentUser","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserProfileUpdate"},"examples":{"update_name":{"summary":"Update Name","value":{"name":"Jamie Ortiz"}},"update_profile":{"summary":"Update Full Profile","value":{"name":"Jamie Ortiz","bio":"Ops lead for the Meridian account","job_role":"engineer","subscribed_to_newsletter":true}}}}},"required":true},"responses":{"200":{"description":"User updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"examples":{"Update Name":{"summary":"Update Name","value":{"email":"jamie.ortiz@meridianfreight.com","name":"Jamie Ortiz","bio":"Ops lead for the Meridian account","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/user/019a2f10-9a4f-7e45-8e86-1c9d4e7b6f11/base.png","subscribed_to_newsletter":true,"job_role":"engineer","id":"019a2f10-9a4f-7e45-8e86-1c9d4e7b6f11","is_onboarding":false}}}}}},"422":{"description":"Unprocessable Entity - Invalid profile\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid profile","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to update user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"security":[{"HTTPBearer":[]}]}},"/user/avatar":{"post":{"tags":["Users"],"summary":"Update User Avatar","description":"Upload and update the current user's avatar image.\n\nAccepts image files up to 5MB in size.\nSupported formats: JPEG, PNG, GIF, WebP","operationId":"uploadUserAvatar","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_uploadUserAvatar","properties":{"file":{"type":"string","format":"binary","description":"Avatar image file"}},"type":"object","required":["file"]},"examples":{"avatar_upload":{"summary":"Avatar Upload","value":{"file":"Binary image data"}}}}},"required":true},"responses":{"200":{"description":"User updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"},"examples":{"Avatar Upload":{"summary":"Avatar Upload","value":{"email":"jamie.ortiz@meridianfreight.com","name":"Jamie Ortiz","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/user/019a2f10-9a4f-7e45-8e86-1c9d4e7b6f11/base.png","subscribed_to_newsletter":true,"job_role":"engineer","id":"019a2f10-9a4f-7e45-8e86-1c9d4e7b6f11","is_onboarding":false}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"400":{"description":"Invalid image format"},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to update avatar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"security":[{"HTTPBearer":[]}]}},"/org/{org_id}/project":{"get":{"tags":["Projects"],"summary":"List Projects","operationId":"listProjects","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor returned from a previous request. Use this to fetch the next page of results.","schema":{"type":"string","format":"uuid"},"example":"0190a234-8dc6-6d08-aea9-928fcecad8f1"},{"name":"page_limit","in":"query","required":false,"description":"Number of results per page","schema":{"type":"integer","default":100,"minimum":1,"maximum":1000}}],"responses":{"200":{"description":"Projects retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_Project_"},"examples":{"multiple_projects":{"summary":"Multiple Projects","value":{"results":[{"id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Support Automation","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/project/019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02/base.png","tasks_oauth_client_id":"019a2f10-8d4f-7e45-8eb0-1c9d4e7b6f04","public_routing_key":"prk_7f3a9c2e1b6d4f80","agent_access_key":"agk_4e8b1f6a2d9c3705","deleted":null},{"id":"019a2f10-8c3e-7e44-9d75-1c9d4e7b6f03","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Invoice Processing","avatar_url":null,"tasks_oauth_client_id":"019a2f10-8e60-7e46-8fc1-1c9d4e7b6f05","public_routing_key":"prk_9a1e5c7b3f2d8064","agent_access_key":"agk_2c6f9a3e8b1d4507","deleted":null}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid pagination"}}},"description":"Bad Request - Invalid pagination\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojects"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list projects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List all projects in the organization.\n\nReturns projects with basic information including:\n- Project ID and name\n- Avatar image URL\n- OAuth client used for running tasks\n- Soft-delete status"},"post":{"tags":["Projects"],"summary":"Create Project","operationId":"createProject","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:create_project"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreate"},"example":{"name":"Support Automation"}}}},"responses":{"200":{"description":"Project created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"example":{"id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Support Automation","avatar_url":null,"tasks_oauth_client_id":"019a2f10-8d4f-7e45-8eb0-1c9d4e7b6f04","public_routing_key":"prk_7f3a9c2e1b6d4f80","agent_access_key":"agk_4e8b1f6a2d9c3705","deleted":null}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid project"}}},"description":"Bad Request - Invalid project\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createproject"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_project permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_project"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"409":{"description":"Conflict - Project name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Project name already exists"}}}},"500":{"description":"Internal Server Error - Failed to create project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a new project in the organization"}},"/org/{org_id}/project/{project_id}":{"get":{"tags":["Projects"],"summary":"Get Project","operationId":"getProject","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Project details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectWithDatasources"},"example":{"id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Support Automation","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/project/019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02/base.png","tasks_oauth_client_id":"019a2f10-8d4f-7e45-8eb0-1c9d4e7b6f04","public_routing_key":"prk_7f3a9c2e1b6d4f80","agent_access_key":"agk_4e8b1f6a2d9c3705","deleted":null,"datasource_connections":[{"id":"019a2f10-a3b6-7e53-96fe-1c9d4e7b6f23","name":"Google Drive – Carrier Documents","private":false,"project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","datasource_id":"019a2f10-a4c7-7e54-9702-1c9d4e7b6f24","created":"2026-01-08T09:00:00Z","modified":"2026-06-02T11:30:00Z","config":{},"datasource":{"id":"019a2f10-a4c7-7e54-9702-1c9d4e7b6f24","name":"google_drive"}}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getproject"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Get detailed project information, including datasource connections"},"post":{"tags":["Projects"],"summary":"Update Project","operationId":"updateProject","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUpdate"},"example":{"name":"Support Automation Prod"}}}},"responses":{"200":{"description":"Project updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"example":{"id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Support Automation Prod","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/project/019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02/base.png","tasks_oauth_client_id":"019a2f10-8d4f-7e45-8eb0-1c9d4e7b6f04","public_routing_key":"prk_7f3a9c2e1b6d4f80","agent_access_key":"agk_4e8b1f6a2d9c3705","deleted":null}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid project"}}},"description":"Bad Request - Invalid project\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateproject"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to update project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update project settings"},"delete":{"tags":["Projects"],"summary":"Delete Project","description":"Soft delete a project.\n\nThis endpoint marks the project as deleted without permanently removing it from\nthe database. The project will no longer appear in listings and cannot be\naccessed through normal operations.\n\n**Important considerations:**\n- This is a soft delete - the project data is retained but marked as deleted\n- All associated tasks, collections, and resources become inaccessible\n- Project members lose access immediately\n- This action requires `create_project` permission on the owning organization\n\n**Recovery:**\nContact support if you need to restore a deleted project.","operationId":"deleteProject","security":[{"HTTPBearer":[]},{"HTTPBearer":["organization:create_project"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Project successfully deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"example":{"id":"019a2f10-8c3e-7e44-9d75-1c9d4e7b6f03","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Invoice Processing","avatar_url":null,"tasks_oauth_client_id":"019a2f10-8e60-7e46-8fc1-1c9d4e7b6f05","public_routing_key":"prk_9a1e5c7b3f2d8064","agent_access_key":"agk_2c6f9a3e8b1d4507","deleted":"2026-07-25T16:20:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deleteproject"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_project permission on organization [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"organization","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_project"}}}}},"description":"Forbidden - Insufficient permissions for organization\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The organization belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to delete project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/config":{"get":{"tags":["Projects"],"summary":"Get Project Config","operationId":"getProjectConfig","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Project configuration details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectConfig"},"example":{"llm":"gpt-4-turbo","temperature":0.3,"knn":6,"chat_system_commands":null,"chat_guardrails":{"input":[{"name":"prompt_policy"}],"output":[{"name":"source_validation"}]},"query_expansion":true,"models_config":{"exclusion_rules":[],"default_model_id":null,"model_preferences":{}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojectconfig"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Get project configuration settings"},"post":{"tags":["Projects"],"summary":"Set Project Config","operationId":"updateProjectConfig","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectConfigUpdate"},"examples":{"basic_config":{"summary":"Basic Configuration","value":{"llm":"gpt-4-turbo","temperature":0.2,"knn":8,"query_expansion":true}}}}}},"responses":{"200":{"description":"Configuration set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectConfig"},"examples":{"Basic Configuration":{"summary":"Basic Configuration","value":{"llm":"gpt-4-turbo","temperature":0.3,"knn":6,"chat_system_commands":null,"chat_guardrails":{"input":[{"name":"prompt_policy"}],"output":[{"name":"source_validation"}]},"query_expansion":true,"models_config":{"exclusion_rules":[],"default_model_id":null,"model_preferences":{}}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid configuration"}}},"description":"Bad Request - Invalid configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateprojectconfig"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid project configuration\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_validation":{"summary":"Request validation failed","value":{"detail":[{"loc":["body"],"msg":"Invalid project configuration","type":"value_error"}]}},"domain_validation":{"summary":"Domain precondition failed","value":{"detail":"Model 'gpt-4-turbo' is not available for this project due to exclusion rules."}}}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to set configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Set project configuration settings"}},"/org/{org_id}/project/{project_id}/avatar":{"post":{"tags":["Projects"],"summary":"Update Project Avatar","operationId":"updateProjectAvatar","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_updateProjectAvatar","type":"object","properties":{"file":{"type":"string","format":"binary","description":"Avatar image file (JPEG, PNG, GIF)"}},"required":["file"]},"examples":{"avatar_upload":{"summary":"Avatar Upload","value":{"file":"Binary image data"}}}}}},"responses":{"200":{"description":"Avatar updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"},"examples":{"Avatar Upload":{"summary":"Avatar Upload","value":{"id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","org_id":"019a2f10-8a1c-7e42-9b53-1c9d4e7b6f01","name":"Support Automation","avatar_url":"https://cdn.rightbrain.ai/assets/avatars/project/019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02/base.png","tasks_oauth_client_id":"019a2f10-8d4f-7e45-8eb0-1c9d4e7b6f04","public_routing_key":"prk_7f3a9c2e1b6d4f80","agent_access_key":"agk_4e8b1f6a2d9c3705","deleted":null}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Invalid image"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateprojectavatar"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"project could not be found"}}}},"500":{"description":"Internal Server Error - Failed to update avatar","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update project avatar image"}},"/org/{org_id}/project/{project_id}/iam/members":{"get":{"tags":["Projects"],"summary":"IAM - List Project Members","description":"Lists all members that have been granted direct access to the project.","operationId":"project_iam_org_org_id_project_project_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view","project:view_members"]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"}],"responses":{"200":{"description":"Successfully retrieved Project members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Iam Org Org Id Project Project Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/iam/members/{member}":{"get":{"tags":["Projects"],"summary":"IAM - Lookup Project Member","description":"Retrieve a specific member that has been granted direct access to the project.","operationId":"project_iam_org_org_id_project_project_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view","project:view_members"]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"}],"responses":{"200":{"description":"Project member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Iam Org Org Id Project Project Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Projects"],"summary":"IAM - Update Project Member","description":"Update the roles that a member holds on the project.","operationId":"project_iam_org_org_id_project_project_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Project member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Project Iam Org Org Id Project Project Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Iam Org Org Id Project Project Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/iam/test":{"post":{"tags":["Projects"],"summary":"IAM - Test Project Permissions","description":"Test the permissions that the caller (or another subject) holds on the project.","operationId":"project_iam_org_org_id_project_project_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Project permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Project Iam Org Org Id Project Project Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Iam Org Org Id Project Project Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/collection":{"get":{"tags":["Collections"],"summary":"List Collections","operationId":"listCollections","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"title","in":"query","required":false,"description":"Filter collections by title (partial match)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor returned from a previous request. Use this to fetch the next page of results.","schema":{"type":"string","format":"uuid"},"example":"0190a234-8dc6-6d08-aea9-928fcecad8f1"},{"name":"page_limit","in":"query","required":false,"description":"Number of results per page","schema":{"type":"integer","default":100,"minimum":1,"maximum":1000}}],"responses":{"200":{"description":"Successfully retrieved collections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_Collection_"},"example":{"results":[{"id":"019a2f10-a194-7e50-93db-1c9d4e7b6f20","title":"Operations Handbook","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","summary":"Standard operating procedures covering dispatch, driver safety, and warehouse workflows.","created":"2026-01-08T09:15:00Z","modified":"2026-06-02T11:40:00Z","embedding_instances":[],"task_ids":[]},{"id":"019a2f10-a2a5-7e51-94ec-1c9d4e7b6f21","title":"Carrier Contracts 2026","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","summary":"Signed carrier rate agreements and service-level terms for the 2026 contract year.","created":"2026-01-20T14:00:00Z","modified":"2026-05-14T16:20:00Z","embedding_instances":[],"task_ids":[]}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listcollections"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"List all collections in a project with optional filtering.\n\nCollections group related documents for use in RAG-enabled tasks and chats.\nResults are paginated and can be filtered by title.\n\n**Use Cases**:\n- Browse available knowledge bases\n- Find collections for specific topics\n- Manage document organization\n- Set up RAG contexts for tasks"},"post":{"tags":["Collections"],"summary":"Create Collection","operationId":"createCollection","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_collection","document_embedding_instance:query"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionCreate"},"examples":{"basic":{"summary":"Basic Collection","value":{"title":"Carrier Contracts 2026","document_embedding_instance_ids":[]}},"with_documents":{"summary":"Collection with Documents","value":{"title":"Operations Handbook","document_embedding_instance_ids":["019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","019a2f10-c3fa-7e72-9931-1c9d4e7b6f42"]}}}}}},"responses":{"200":{"description":"Collection created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"},"examples":{"Basic Collection":{"summary":"Basic Collection","value":{"id":"019a2f10-a2a5-7e51-94ec-1c9d4e7b6f21","title":"Carrier Contracts 2026","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","summary":"Signed carrier rate agreements and service-level terms for the 2026 contract year.","created":"2026-07-20T10:00:00Z","modified":"2026-07-20T10:00:00Z","embedding_instances":[],"task_ids":[]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createcollection"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Create a new collection for organizing document embeddings.\n\nCollections serve as knowledge bases for RAG-enabled features:\n- Group related documents together\n- Enable contextual AI responses\n- Support multiple embedding instances\n- Organize information by topic or use case\n\nYou can add documents to the collection after creation."}},"/org/{org_id}/project/{project_id}/collection/{collection_id}":{"get":{"tags":["Collections"],"summary":"Get Collection Details","operationId":"getCollection","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:view"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"description":"The UUID of the collection","schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Collection details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"},"example":{"id":"019a2f10-a194-7e50-93db-1c9d4e7b6f20","title":"Operations Handbook","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","summary":"Standard operating procedures covering dispatch, driver safety, and warehouse workflows.","created":"2026-01-08T09:15:00Z","modified":"2026-06-02T11:40:00Z","embedding_instances":[{"id":"019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","is_active":true,"config":{}}],"task_ids":["019a2f10-e11c-7e90-9b53-1c9d4e7b6f60"]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getcollection"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on collection [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"collection","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for collection\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The collection belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Retrieve detailed information about a specific collection.\n\nReturns complete collection metadata including:\n- Title\n- Summary\n- Associated embedding instances\n- Associated task IDs\n- Creation and update timestamps"},"post":{"tags":["Collections"],"summary":"Edit Collection","operationId":"editCollection","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:edit","document_embedding_instance:query"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Collection Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionUpdate"},"examples":{"update_title":{"summary":"Update Title","value":{"title":"Operations Handbook — 2026 Revision"}}}}}},"responses":{"200":{"description":"Collection updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"},"examples":{"Update Title":{"summary":"Update Title","value":{"id":"019a2f10-a194-7e50-93db-1c9d4e7b6f20","title":"Operations Handbook — 2026 Revision","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","summary":"Standard operating procedures covering dispatch, driver safety, and warehouse workflows.","created":"2026-01-08T09:15:00Z","modified":"2026-07-20T10:15:00Z","embedding_instances":[{"id":"019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","is_active":true,"config":{}}],"task_ids":["019a2f10-e11c-7e90-9b53-1c9d4e7b6f60"]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Editcollection"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Update a collection's title.\n\nThis endpoint only supports changing the title. To change document\nmembership, use the dedicated `/collection/{collection_id}/add` and\n`/collection/{collection_id}/remove` endpoints instead.\n\nChanges take effect immediately for all users of the collection."}},"/org/{org_id}/project/{project_id}/collection/{collection_id}/stats":{"get":{"tags":["Collections"],"summary":"Get Collection Statistics","operationId":"getCollectionStats","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:view"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","title":"Collection Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Collection statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionStatsResponse"},"examples":{"stats":{"summary":"Collection Statistics","value":{"documents_by_source":[{"source":"upload","count":45},{"source":"web_scrape","count":12},{"source":"gdrive","count":8}],"number_of_chats":23}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getcollectionstats"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on collection [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"collection","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for collection\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The collection belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Retrieve statistics about a collection's contents and usage.\n\nProvides insights into:\n- Document distribution by source type\n- Number of associated chats\n\nUseful for understanding collection composition and usage patterns."}},"/org/{org_id}/project/{project_id}/collection/{collection_id}/query":{"post":{"tags":["Collections"],"summary":"Query Collection","operationId":"queryCollection","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:query"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Collection Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionQuery"},"examples":{"simple":{"summary":"Simple Query","value":{"query":"What is the notice period for terminating a carrier contract?"}},"with_limit":{"summary":"Query with Limit","value":{"query":"Which carriers have fuel surcharge clauses?","limit":20}}}}}},"responses":{"200":{"description":"The synthesized answer to the query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionQueryResult"},"examples":{"Simple Query":{"summary":"Simple Query","value":{"response":"Either party may terminate the agreement with 90 days' written notice, or immediately for uncured material breach.","query":"What is the notice period for terminating a carrier contract?"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Querycollection"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have query permission on collection [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"collection","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"query"}}}}},"description":"Forbidden - Insufficient permissions for collection\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The collection belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Ask a question about a collection's contents.\n\nRuns a retrieval-augmented QA chain over the collection's embedded documents\nand returns a single synthesized natural-language answer, not a list of\nmatching chunks.\n\n**Use Cases**:\n- Get a direct answer grounded in a collection's documents\n- Test RAG answer quality\n- Build custom Q&A interfaces"}},"/org/{org_id}/project/{project_id}/collection/{collection_id}/update_summary":{"post":{"tags":["Collections"],"summary":"Update Collection Summary","operationId":"updateCollectionSummary","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:edit"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Collection Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Summary generation job started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncJobResult"},"examples":{"job_started":{"summary":"Job Started","value":{"task_id":["019a2f10-f4d4-7e96-9b86-1c9d4e7b6f72"],"status":"pending"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatecollectionsummary"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on collection [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"collection","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for collection\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The collection belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Generate and update the AI-generated summary for a collection.\n\nTriggers an asynchronous job to:\n- Analyze all documents in the collection\n- Generate a comprehensive summary\n- Update the collection's summary field\n\nThe summary helps users understand the collection's content at a glance."}},"/org/{org_id}/project/{project_id}/collection/{collection_id}/add":{"post":{"tags":["Collections"],"summary":"Add Documents to Collection","operationId":"addToCollection","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:edit","document_embedding_instance:query"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Collection Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionEmbeddingUpdate"},"examples":{"add_documents":{"summary":"Add Documents","value":{"embedding_instance_ids":["019a2f10-c3fa-7e72-9931-1c9d4e7b6f42"]}}}}}},"responses":{"200":{"description":"Documents added to the collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"},"examples":{"Add Documents":{"summary":"Add Documents","value":{"id":"019a2f10-a194-7e50-93db-1c9d4e7b6f20","title":"Operations Handbook","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","summary":"Standard operating procedures covering dispatch, driver safety, and warehouse workflows.","created":"2026-01-08T09:15:00Z","modified":"2026-06-02T11:40:00Z","embedding_instances":[{"id":"019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","is_active":true,"config":{}},{"id":"019a2f10-c3fa-7e72-9931-1c9d4e7b6f42","chat_document_id":"019a2f10-b3d8-7e62-9721-1c9d4e7b6f32","is_active":true,"config":{}}],"task_ids":["019a2f10-e11c-7e90-9b53-1c9d4e7b6f60"]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Addtocollection"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Add embedding instances (documents) to an existing collection.\n\nExpands the collection's knowledge base by including additional documents.\nThe documents must already exist as embedding instances in the system."}},"/org/{org_id}/project/{project_id}/collection/{collection_id}/remove":{"post":{"tags":["Collections"],"summary":"Remove Documents from Collection","operationId":"removeFromCollection","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:edit"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Collection Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionEmbeddingUpdate"},"examples":{"remove_documents":{"summary":"Remove Documents","value":{"embedding_instance_ids":["019a2f10-c3fa-7e72-9931-1c9d4e7b6f42"]}}}}}},"responses":{"200":{"description":"Documents removed from the collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"},"examples":{"Remove Documents":{"summary":"Remove Documents","value":{"id":"019a2f10-a194-7e50-93db-1c9d4e7b6f20","title":"Operations Handbook","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","summary":"Standard operating procedures covering dispatch, driver safety, and warehouse workflows.","created":"2026-01-08T09:15:00Z","modified":"2026-06-02T11:40:00Z","embedding_instances":[{"id":"019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","is_active":true,"config":{}}],"task_ids":["019a2f10-e11c-7e90-9b53-1c9d4e7b6f60"]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Removefromcollection"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on collection [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"collection","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for collection\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The collection belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Embedding instance ID not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find embedding_instance_id [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"embedding_instance_id","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Remove embedding instances (documents) from a collection.\n\nReduces the collection's scope by excluding specific documents.\nDocuments are not deleted, only their association with the collection is removed."}},"/org/{org_id}/project/{project_id}/collection/{collection_id}/iam/members":{"get":{"tags":["Collections"],"summary":"IAM - List Collection Members","description":"Lists all members that have been granted direct access to the collection.","operationId":"collection_iam_org_org_id_project_project_id_collection_collection_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:view","collection:view_members"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Collection Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Collection members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Collection Iam Org Org Id Project Project Id Collection Collection Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/collection/{collection_id}/iam/members/{member}":{"get":{"tags":["Collections"],"summary":"IAM - Lookup Collection Member","description":"Retrieve a specific member that has been granted direct access to the collection.","operationId":"collection_iam_org_org_id_project_project_id_collection_collection_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:view","collection:view_members"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Collection Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Collection member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Collection Iam Org Org Id Project Project Id Collection Collection Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Collections"],"summary":"IAM - Update Collection Member","description":"Update the roles that a member holds on the collection.","operationId":"collection_iam_org_org_id_project_project_id_collection_collection_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:view"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Collection Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Collection member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Collection Iam Org Org Id Project Project Id Collection Collection Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Collection Iam Org Org Id Project Project Id Collection Collection Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/collection/{collection_id}/iam/test":{"post":{"tags":["Collections"],"summary":"IAM - Test Collection Permissions","description":"Test the permissions that the caller (or another subject) holds on the collection.","operationId":"collection_iam_org_org_id_project_project_id_collection_collection_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["collection:view"]}],"parameters":[{"name":"collection_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Collection Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Collection permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Collection Iam Org Org Id Project Project Id Collection Collection Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Collection Iam Org Org Id Project Project Id Collection Collection Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/audit_event":{"get":{"tags":["Audit Events"],"summary":"List Project Audit Events","operationId":"listProjectAuditEvents","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Event Type"},"description":"Filter by one or more audit event types."},{"name":"actor_user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor User Id"},"description":"Filter by the acting user."},{"name":"resource_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"description":"Filter by resource type."},{"name":"resource_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id"},"description":"Filter by resource identifier."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Date"},"description":"Only include events occurring at or after this UTC timestamp."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date"},"description":"Only include events occurring at or before this UTC timestamp."}],"responses":{"200":{"description":"Project audit events retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_AuditEventListItem_"},"example":{"results":[{"id":"0195a234-1111-2222-3333-444444444444","project_id":"0190a234-9876-5432-10ab-cdef01234567","org_id":"0190a234-5678-9abc-def0-123456789abc","actor_user_id":"0190c234-1111-2222-3333-444444444444","event_type":"task.create","resource_type":"task","resource_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","message":"Created task \"Content Summarizer\"","labels":{},"occurred_at":"2026-04-09T12:34:56.123456Z","created":"2026-04-09T12:34:56.223456Z"}],"pagination":{"next_cursor":"eyJpZCI6IjAxOTVhMjM0LTExMTEtMjIyMi0zMzMzLTQ0NDQ0NDQ0NDQ0NCIsIm9jY3VycmVkX2F0IjoiMjAyNi0wNC0wOVQxMjozNDo1Ni4xMjM0NTZaIn0","has_next":true,"page_limit":100}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid audit event filters"}}},"description":"Bad Request - Invalid audit event filters\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojectauditevents"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to list audit events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List immutable audit events recorded for a project.\n\nResults are ordered by `occurred_at` descending, then `id` descending. The `cursor`\nparameter is an opaque pagination token and must be treated as an unreadable value by\nclients.\n\nUse the filters to narrow the feed by event type, actor, or resource identifiers."}},"/org/{org_id}/project/{project_id}/audit_event/export":{"get":{"tags":["Audit Events"],"summary":"Export Project Audit Events","operationId":"exportProjectAuditEvents","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"event_type","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Event Type"},"description":"Filter by one or more audit event types."},{"name":"actor_user_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor User Id"},"description":"Filter by the acting user."},{"name":"resource_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"description":"Filter by resource type."},{"name":"resource_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id"},"description":"Filter by resource identifier."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Date"},"description":"Only include events occurring at or after this UTC timestamp."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date"},"description":"Only include events occurring at or before this UTC timestamp."}],"responses":{"200":{"description":"Audit events exported as NDJSON","content":{"application/json":{"schema":{}},"application/x-ndjson":{"schema":{"type":"string"},"example":"{\"id\":\"0195a234-1111-2222-3333-444444444444\",\"project_id\":\"0190a234-9876-5432-10ab-cdef01234567\",\"org_id\":\"0190a234-5678-9abc-def0-123456789abc\",\"actor_user_id\":\"0190c234-1111-2222-3333-444444444444\",\"event_type\":\"task.create\",\"resource_type\":\"task\",\"resource_id\":\"0190a234-8dc6-6d08-aea9-928fcecad8f1\",\"message\":\"Created task \\\"Content Summarizer\\\"\",\"labels\":{},\"occurred_at\":\"2026-04-09T12:34:56.123456Z\",\"created\":\"2026-04-09T12:34:56.223456Z\",\"payload\":{\"id\":\"0190a234-8dc6-6d08-aea9-928fcecad8f1\",\"name\":\"Content Summarizer\"}}"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid audit event filters"}}},"description":"Bad Request - Invalid audit event filters\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Exportprojectauditevents"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to export audit events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Export project audit events as NDJSON.\n\nEach line is a full audit event detail record, including the decrypted payload."}},"/org/{org_id}/project/{project_id}/audit_event/integrity":{"get":{"tags":["Audit Events"],"summary":"Get Project Audit Integrity Status","operationId":"getProjectAuditIntegrityStatus","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Audit integrity state head retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditIntegrityStatus"},"example":{"project_id":"0190a234-9876-5432-10ab-cdef01234567","verified":null,"state_verified":true,"latest_sequence":123,"latest_event_id":"0195a234-1111-2222-3333-444444444444","latest_event_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojectauditintegritystatus"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve audit integrity status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Return the authenticated project audit-chain head.\n\nProject audit logs are cryptographically verifiable and tamper-evident for retained\nrows. This endpoint verifies only the chain-head state MAC and does not scan all audit\nevents. Use the full verification endpoint to recompute the event chain from genesis.\n\nThis guarantee assumes the application runtime and KMS decrypt permissions are not\ncompromised. It does not prove that every business action emitted an audit event,\nprevent project deletion, provide legal retention, or provide external anchoring."}},"/org/{org_id}/project/{project_id}/audit_event/integrity/verify":{"post":{"tags":["Audit Events"],"summary":"Verify Project Audit Integrity","operationId":"verifyProjectAuditIntegrity","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Audit integrity verification completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditIntegrityVerification"},"examples":{"verified":{"summary":"Verified audit chain","value":{"verified":true,"status":"verified","checked_events":123,"latest_sequence":123,"latest_event_id":"0195a234-1111-2222-3333-444444444444","latest_event_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}},"failed":{"summary":"Tampering detected","value":{"verified":false,"status":"failed","checked_events":41,"latest_sequence":123,"latest_event_id":"0195a234-1111-2222-3333-444444444444","latest_event_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","first_failure":{"sequence_num":42,"audit_event_id":"0195a234-5555-6666-7777-888888888888","reason":"event_hash_mismatch","expected_hash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","actual_hash":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Verifyprojectauditintegrity"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to verify audit integrity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Recompute and verify the retained project audit-event HMAC chain.\n\nVerification decrypts audit payloads internally, recomputes each canonical event HMAC\nfrom plaintext logical event values, verifies previous-hash linkage, verifies the\nauthenticated chain-head state, and requires the recomputed latest event head to match\nthat authenticated state. The response does not include decrypted payloads or canonical\nevent bodies."}},"/org/{org_id}/project/{project_id}/audit_event/{audit_event_id}":{"get":{"tags":["Audit Events"],"summary":"Get Project Audit Event","operationId":"getProjectAuditEvent","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"audit_event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Audit Event Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Audit event details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventDetail"},"example":{"id":"0195a234-1111-2222-3333-444444444444","project_id":"0190a234-9876-5432-10ab-cdef01234567","org_id":"0190a234-5678-9abc-def0-123456789abc","actor_user_id":"0190c234-1111-2222-3333-444444444444","event_type":"task.create","resource_type":"task","resource_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","message":"Created task \"Content Summarizer\"","labels":{},"occurred_at":"2026-04-09T12:34:56.123456Z","created":"2026-04-09T12:34:56.223456Z","payload":{"id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","name":"Content Summarizer"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojectauditevent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"audit_event_id not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find audit_event_id [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"audit_event_id","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve audit event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve a single audit event for the project.\n\nThe detail response includes the decrypted payload captured for the event."}},"/org/{org_id}/project/{project_id}/document":{"post":{"tags":["Documents"],"summary":"Create Documents","operationId":"createDocuments","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_document"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_createDocuments"},"examples":{"single_file":{"summary":"One uploaded file","description":"One descriptor for one uploaded file. `strategy` is the only field that affects the result here — see the note above.","value":{"data":"[{\"strategy\": \"txt\"}]","files":["Binary file content"]}},"fetched_url":{"summary":"A URL with no uploaded file","description":"A descriptor with no corresponding uploaded file must carry `target`. `files` is then omitted entirely.","value":{"data":"[{\"strategy\": \"url\", \"target\": \"https://example.com/driver-safety-sop\"}]"}}}}}},"responses":{"200":{"description":"Documents accepted for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentStatusResponse"},"examples":{"processing":{"summary":"One uploaded file","description":"This is the immediate response to the request; tasks typically start out `PENDING` with no `info` yet. Poll `GET /document/create/status/{group_id}` to track them through to completion.","value":{"group_id":"019a2f10-f5e5-7e97-9b97-1c9d4e7b6f73","task_count":2,"tasks":[{"task_id":"019a2f10-f6f6-7e98-9ba8-1c9d4e7b6f74","state":"PENDING","info":null},{"task_id":"019a2f10-f707-7e99-9bb9-1c9d4e7b6f75","state":"PENDING","info":null}]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createdocuments"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_document permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_document"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Upload and process documents for use in collections and RAG.\n\nSupports the following content strategies:\n- PDF documents (with OCR fallback for scanned pages)\n- Word documents (docx) and spreadsheets (xlsx)\n- Plain text files (txt)\n- CSV files\n- Git repositories\n- Web pages (url) and YouTube videos\n- Zip archives\n\nDocuments are processed asynchronously:\n1. Files are uploaded and validated\n2. Content is extracted and chunked\n3. Embeddings are generated\n4. Documents become available for collections\n\nReturns a group ID to track processing status.\n\nBecause extraction happens after this endpoint has already responded, a file that\nturns out to hold no extractable content does not fail this request. It fails its\nown processing task, which is reported per-file by\n`GET /org/{org_id}/project/{project_id}/document/create/status/{group_id}`.\nThat task reaches state `REJECTED`, and its `info` carries the same `reason` and\n`message` the synchronous upload endpoint returns in its `400`, so the cause can\nbe distinguished programmatically there.\n\nA file can also fail for a reason that is ours rather than the file's — the\nextraction service being unavailable, for instance. That task reaches `FAILURE`,\nand its `info` is a description of the error rather than a `{reason, message}`\nobject, so branch on `state` before reading `info`.\n\nThree states are terminal: `SUCCESS`, `REJECTED` and `FAILURE`. Neither\n`REJECTED` nor `FAILURE` is retried, and because `completed` counts only the\ntasks that succeeded it never reaches `upload_count` once any file has failed —\npoll until every task has reached one of the three rather than waiting on\n`completed`.\n\nTreat a `state` of `null` as terminal too. It means we could not read that task\nback at all, and that does not resolve on a later poll.\n\nEach item in the `data` array must include a `strategy`, one of: `csv`, `docx`, `git`, `pdf`, `txt`, `url`, `xlsx`, `youtube`, `zip`.\n\nDescriptors are matched positionally to the uploaded `files`: the first `data` item corresponds to the first uploaded file, and so on. `target` is optional for a descriptor paired with an uploaded file. It is required only for descriptors with no corresponding uploaded file (for example, a `url` or `youtube` strategy that fetches content directly), where it must contain the source location to fetch.\n\nA descriptor paired with an uploaded file does not name the document: `title` and `description` sent in the descriptor are ignored for uploaded files. The created document's `title` is the uploaded filename and its `description` is `null`. Rename it afterwards with `POST /document/{document_id}`."},"get":{"tags":["Documents"],"summary":"List Documents","operationId":"listDocuments","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:list_documents"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"connection_id","in":"query","required":false,"description":"Filter by datasource connection","schema":{"type":"string","format":"uuid"}},{"name":"title","in":"query","required":false,"description":"Filter by title (partial match)","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor","schema":{"type":"string","format":"uuid"}},{"name":"collection_id","in":"query","required":false,"description":"Filter by collection membership","schema":{"type":"string","format":"uuid"}},{"name":"page_limit","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"source","in":"query","required":false,"description":"Filter by where the document came from. Documents created through either upload endpoint have `source: upload`; the remaining values belong to documents synced from a datasource connection.","schema":{"anyOf":[{"$ref":"#/components/schemas/DocumentSource"},{"type":"null"}],"title":"Source"}},{"name":"strategy","in":"query","required":false,"description":"Filter by processing strategy","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_ChatDocument_"},"example":{"results":[{"id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","title":"Driver Safety SOP","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","description":"Standard operating procedure for pre-trip vehicle checks and incident reporting.","source":"upload","strategy":"pdf","source_meta":null,"connection_id":null,"chunks":42,"original_mime":"application/pdf","embedding_instances":[{"id":"019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","is_active":true,"config":{}}]},{"id":"019a2f10-b2c7-7e61-960e-1c9d4e7b6f31","title":"Union Pacific Rate Agreement 2026","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","description":"Signed rate agreement and service-level terms with Union Pacific for the 2026 contract year.","source":"upload","strategy":"pdf","source_meta":null,"connection_id":null,"chunks":18,"original_mime":"application/pdf","embedding_instances":[{"id":"019a2f10-c2e9-7e71-9820-1c9d4e7b6f41","chat_document_id":"019a2f10-b2c7-7e61-960e-1c9d4e7b6f31","is_active":true,"config":{}}]}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listdocuments"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have list_documents permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"list_documents"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"List all documents in a project with optional filtering.\n\nFilter options:\n- By connection/datasource\n- By title (partial match)\n- By collection membership\n- By source type\n- By processing strategy\n\nResults are paginated and include document metadata."}},"/org/{org_id}/project/{project_id}/document/upload":{"post":{"tags":["Documents"],"summary":"Upload Document","operationId":"uploadProjectDocuments","deprecated":true,"security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_document"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_uploadProjectDocuments"},"examples":{"single_file":{"summary":"One uploaded file","description":"One descriptor for one uploaded file. `strategy` is the only field that affects the result here — see the note above.","value":{"data":"[{\"strategy\": \"txt\"}]","files":["Binary file content"]}},"fetched_url":{"summary":"A URL with no uploaded file","description":"A descriptor with no corresponding uploaded file must carry `target`. `files` is then omitted entirely.","value":{"data":"[{\"strategy\": \"url\", \"target\": \"https://example.com/driver-safety-sop\"}]"}}}}}},"responses":{"200":{"description":"Documents uploaded and processed","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChatDocument"},"title":"Response Uploadprojectdocuments"},"examples":{"One uploaded file":{"summary":"One uploaded file","value":[{"id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","title":"Driver Safety SOP","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","description":"Standard operating procedure for pre-trip vehicle checks and incident reporting.","source":"upload","strategy":"pdf","source_meta":null,"connection_id":null,"chunks":42,"original_mime":"application/pdf","embedding_instances":[{"id":"019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","is_active":true,"config":{}}]},{"id":"019a2f10-b2c7-7e61-960e-1c9d4e7b6f31","title":"Union Pacific Rate Agreement 2026","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","description":"Signed rate agreement and service-level terms with Union Pacific for the 2026 contract year.","source":"upload","strategy":"pdf","source_meta":null,"connection_id":null,"chunks":18,"original_mime":"application/pdf","embedding_instances":[{"id":"019a2f10-c2e9-7e71-9820-1c9d4e7b6f41","chat_document_id":"019a2f10-b2c7-7e61-960e-1c9d4e7b6f31","is_active":true,"config":{}}]}]}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/NoDocumentContentExtractedErrorResponse"},{"$ref":"#/components/schemas/NoUsableDocumentContentErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Uploadprojectdocuments"},"examples":{"no_content_extracted":{"summary":"The file was read and held no text","value":{"detail":{"reason":"NO_DOCUMENT_CONTENT_EXTRACTED","message":"No content could be extracted from 'scan.pdf'. The file may be empty, image-only, or password protected.","noDocumentContentExtractedError":{"field":"files","value":"scan.pdf"}}}},"no_usable_content":{"summary":"The file could not be read","value":{"detail":{"reason":"NO_USABLE_DOCUMENT_CONTENT","message":"No usable content could be processed from 'records.csv'. The file could not be parsed as CSV.","noUsableDocumentContentError":{"field":"files","value":"records.csv"}}}},"malformed_identifier":{"summary":"The project identifier was not a UUID","value":{"detail":{"reason":"MALFORMED_RESOURCE_IDENTIFIER","message":"Resource identifier value provided for field 'project_id' is malformed (expected UUID)","malformedResourceIdentifierError":{"field":"project_id","value":"not-a-uuid","expected_format":"UUID"}}}}}}},"description":"Bad Request - the file could not be turned into any documents, or the project identifier was malformed"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Uploadprojectdocuments"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_document permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_document"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"413":{"description":"File too large"},"500":{"description":"Internal Server Error - Failed to upload document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Upload and process documents synchronously, returning the created\ndocuments directly in the response body.\n\nDeprecated in favor of `POST /document`, which processes documents\nasynchronously and returns a job ID for tracking status.\n\nEach item in the `data` array must include a `strategy`, one of: `csv`, `docx`, `git`, `pdf`, `txt`, `url`, `xlsx`, `youtube`, `zip`.\n\nDescriptors are matched positionally to the uploaded `files`: the first `data` item corresponds to the first uploaded file, and so on. `target` is optional for a descriptor paired with an uploaded file. It is required only for descriptors with no corresponding uploaded file (for example, a `url` or `youtube` strategy that fetches content directly), where it must contain the source location to fetch.\n\nA descriptor paired with an uploaded file does not name the document: `title` and `description` sent in the descriptor are ignored for uploaded files. The created document's `title` is the uploaded filename and its `description` is `null`. Rename it afterwards with `POST /document/{document_id}`."}},"/org/{org_id}/project/{project_id}/document/create/status/{group_id}":{"get":{"tags":["Documents"],"summary":"Check Document Processing Status","operationId":"getDocumentStatus","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_document"]}],"parameters":[{"name":"group_id","in":"path","required":true,"description":"The group ID from document creation","schema":{"type":"string"},"example":"019a2f10-f5e5-7e97-9b97-1c9d4e7b6f73"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Document processing status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentProcessingStatus"},"examples":{"in_progress":{"summary":"Partially Complete","description":"Keep polling a task only while its `state` is one it has not finished in: `PENDING`, `RECEIVED`, `STARTED`, `PROGRESS` or `RETRY`. In practice an upload reports `PENDING` until it finishes, because this pipeline neither retries nor reports progress. Treat every other value as final for that task — `REVOKED` and `null` included, not just the states described below.\n\n`info` depends on `state`, so branch on `state` before reading it. For a completed task (`SUCCESS`) it is the full created document (the same shape returned by `GET /document/{document_id}`). For a file no content could be extracted from (`REJECTED`) it is the same `{reason, message, ...}` body the synchronous upload endpoint returns in its `400`. For a task that failed on our side (`FAILURE`) it is a description of the error, not an object. For a task that hasn't finished yet it is `null`. Neither `REJECTED` nor `FAILURE` is retried.\n\nA `state` of `null` means that task's result could not be read back: its siblings are still reported, and it will read the same way on a later poll, so treat it as final. That is distinct from us being unable to reach the result store at all, which fails the whole request with a `500` and is worth retrying.","value":{"group_id":"019a2f10-f5e5-7e97-9b97-1c9d4e7b6f73","upload_count":5,"completed":1,"tasks":[{"task_id":"019a2f10-f6f6-7e98-9ba8-1c9d4e7b6f74","state":"SUCCESS","info":{"id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","title":"Driver Safety SOP","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","description":"Standard operating procedure for pre-trip vehicle checks and incident reporting.","source":"upload","strategy":"pdf","source_meta":null,"connection_id":null,"chunks":42,"original_mime":"application/pdf","embedding_instances":[{"id":"019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","is_active":true,"config":{}}]}},{"task_id":"019a2f10-f707-7e99-9bb9-1c9d4e7b6f75","state":"REJECTED","info":{"reason":"NO_DOCUMENT_CONTENT_EXTRACTED","message":"No content could be extracted from 'scan.pdf'. The file may be empty, image-only, or password protected.","noDocumentContentExtractedError":{"field":"files","value":"scan.pdf"}}},{"task_id":"019a2f10-f718-7e9a-9bca-1c9d4e7b6f76","state":"FAILURE","info":"<class 'ValueError'> : Error processing document: HTTP 500"},{"task_id":"019a2f10-f729-7e9b-9bdb-1c9d4e7b6f77","state":null,"info":null},{"task_id":"019a2f10-f73a-7e9c-9bec-1c9d4e7b6f78","state":"PENDING","info":null}]}}}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceNotFoundErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find group_id [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"group_id","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}},"description":"Not Found - no group with this ID.\n\nAn upload is recorded before its tasks are published, so an accepted upload always hands back an ID that resolves: this means an ID we never issued, or one whose results the store has since expired. Treat it as terminal rather than retrying the poll."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getdocumentstatus"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_document permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_document"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"500":{"description":"Internal Server Error - Failed to check document processing status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Check the status of document processing tasks.\n\nMonitor the progress of:\n- File upload and validation\n- Content extraction\n- Embedding generation\n- Error handling\n\nUse the group_id returned from document creation to track all related tasks."}},"/org/{org_id}/project/{project_id}/document/{document_id}/query":{"post":{"tags":["Documents"],"summary":"Query Document Content","operationId":"queryDocument","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:query"]}],"parameters":[{"name":"document_id","in":"path","required":true,"description":"The UUID of the document","schema":{"type":"string","format":"uuid"},"example":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"query","in":"query","required":true,"description":"Search query","schema":{"type":"string"},"example":"What are the pre-trip inspection requirements?"}],"responses":{"200":{"description":"Ranked chunks matching the query","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChatDocumentQueryResult"},"title":"Response Querydocument"},"example":[{"chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","text":"Drivers must complete a pre-trip inspection checklist covering brakes, lights, and cargo securement before departing the yard.","score":0.91},{"chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","text":"Any collision, near-miss, or cargo shift must be reported to dispatch within 30 minutes of occurrence.","score":0.84}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Querydocument"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have query permission on document [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"document","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"query"}}}}},"description":"Forbidden - Insufficient permissions for document\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The document belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Document not found"}}}}},"description":"Search within a specific document using semantic search.\n\nPerforms vector similarity search on the document's embedded chunks to find\nrelevant content. Useful for:\n- Finding specific information in large documents\n- Testing embedding quality\n- Building document Q&A features\n- Extracting key passages\n\nReturns ranked chunks with relevance scores."}},"/org/{org_id}/project/{project_id}/document/{document_id}":{"get":{"tags":["Documents"],"summary":"Get Document Details","operationId":"getDocument","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:view"]}],"parameters":[{"name":"document_id","in":"path","required":true,"description":"The UUID of the document","schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Document details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatDocument"},"example":{"id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","title":"Driver Safety SOP","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","description":"Standard operating procedure for pre-trip vehicle checks and incident reporting.","source":"upload","strategy":"pdf","source_meta":null,"connection_id":null,"chunks":42,"original_mime":"application/pdf","embedding_instances":[{"id":"019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","is_active":true,"config":{}}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getdocument"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on document [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"document","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for document\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The document belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Retrieve detailed information about a specific document.\n\nReturns:\n- Document metadata (title, description, source, strategy, original MIME type)\n- Chunk count\n- Associated embedding instances\n\nDoes not include the actual document content."},"post":{"tags":["Documents"],"summary":"Update Document","operationId":"updateDocument","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:edit"]}],"parameters":[{"name":"document_id","in":"path","required":true,"description":"The UUID of the document","schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatDocumentUpdate"},"examples":{"update_title":{"summary":"Update Title","value":{"title":"Driver Safety SOP — Revised"}},"full_update":{"summary":"Full Update","value":{"title":"Union Pacific Rate Agreement 2026","description":"Updated after the Q3 rate renegotiation."}}}}}},"responses":{"200":{"description":"Document updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatDocument"},"examples":{"Update Title":{"summary":"Update Title","value":{"id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","title":"Driver Safety SOP — Revised","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","description":"Standard operating procedure for pre-trip vehicle checks and incident reporting.","source":"upload","strategy":"pdf","source_meta":null,"connection_id":null,"chunks":42,"original_mime":"application/pdf","embedding_instances":[{"id":"019a2f10-c1d8-7e70-971f-1c9d4e7b6f40","chat_document_id":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30","is_active":true,"config":{}}]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatedocument"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on document [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"document","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for document\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The document belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Update document metadata such as title or description.\n\nAllows modification of:\n- Document title\n- Description\n\nDoes not re-process the document content or embeddings."},"delete":{"tags":["Documents"],"summary":"Delete Document","operationId":"deleteDocument","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:edit"]}],"parameters":[{"name":"document_id","in":"path","required":true,"description":"The UUID of the document to delete","schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"The document was deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatDocument"},"example":{"id":"019a2f10-b3d8-7e62-9721-1c9d4e7b6f32","title":"Fuel Surcharge Policy","project_id":"019a2f10-8b2d-7e43-9c64-1c9d4e7b6f02","description":"Superseded fuel surcharge calculation policy, replaced by the 2026 carrier rate agreements.","source":"upload","strategy":"pdf","source_meta":null,"connection_id":null,"chunks":6,"original_mime":"application/pdf","embedding_instances":[{"id":"019a2f10-c3fa-7e72-9931-1c9d4e7b6f42","chat_document_id":"019a2f10-b3d8-7e62-9721-1c9d4e7b6f32","is_active":true,"config":{}}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletedocument"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on document [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"document","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for document\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The document belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Document not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find document [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"document","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Delete a document and all associated data.\n\nThis action:\n- Removes the document from all collections\n- Deletes all embeddings and chunks\n- Removes the document metadata\n- Cannot be undone\n\nThe document will no longer be available for RAG or queries.\n\nReturns the deleted document, including its embedding instances, in the response\nbody."}},"/org/{org_id}/project/{project_id}/document/{document_id}/embeddings":{"get":{"tags":["Documents"],"summary":"List Document Embeddings","operationId":"listDocumentEmbeddings","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:view"]}],"parameters":[{"name":"document_id","in":"path","required":true,"description":"The UUID of the document","schema":{"type":"string","format":"uuid"},"example":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor","schema":{"type":"string","format":"uuid"}},{"name":"page_limit","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":25}}],"responses":{"200":{"description":"Successfully retrieved document embeddings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_ChatDocumentEmbeddingRecord_"},"example":{"results":[{"id":"019a2f10-d1fa-7e80-9931-1c9d4e7b6f50","document":"Drivers must complete a pre-trip inspection checklist covering brakes, lights, and cargo securement before departing the yard."},{"id":"019a2f10-d20b-7e81-9a42-1c9d4e7b6f51","document":"Any collision, near-miss, or cargo shift must be reported to dispatch within 30 minutes of occurrence."}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listdocumentembeddings"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on document [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"document","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for document\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The document belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"List all embedding chunks for a document.\n\nReturns a paginated set of embedding records. Each record includes the\nchunk's `id` and its underlying `document` text.\n\nUseful for debugging RAG performance and understanding document processing."}},"/org/{org_id}/project/{project_id}/document/{document_id}/embedding/{embedding_id}":{"get":{"tags":["Documents"],"summary":"Get Embedding Details","operationId":"getDocumentEmbedding","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:view"]}],"parameters":[{"name":"document_id","in":"path","required":true,"description":"The UUID of the document","schema":{"type":"string","format":"uuid"},"example":"019a2f10-b1b6-7e60-95fd-1c9d4e7b6f30"},{"name":"embedding_id","in":"path","required":true,"description":"The UUID of the embedding","schema":{"type":"string","format":"uuid"},"example":"019a2f10-d1fa-7e80-9931-1c9d4e7b6f50"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Embedding details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatDocumentEmbeddingRecord"},"example":{"id":"019a2f10-d1fa-7e80-9931-1c9d4e7b6f50","document":"Drivers must complete a pre-trip inspection checklist covering brakes, lights, and cargo securement before departing the yard."}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getdocumentembedding"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on document [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"document","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for document\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The document belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Fetch details of a specific embedding chunk.\n\nReturns the embedding record's `id` and its underlying `document` text.\n\nUseful for examining what content is being retrieved in RAG queries."}},"/org/{org_id}/project/{project_id}/document/{document_id}/iam/members":{"get":{"tags":["Documents"],"summary":"IAM - List Document Members","description":"Lists all members that have been granted direct access to the document.","operationId":"document_iam_org_org_id_project_project_id_document_document_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:view","document:view_members"]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Document members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Document Iam Org Org Id Project Project Id Document Document Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/document/{document_id}/iam/members/{member}":{"get":{"tags":["Documents"],"summary":"IAM - Lookup Document Member","description":"Retrieve a specific member that has been granted direct access to the document.","operationId":"document_iam_org_org_id_project_project_id_document_document_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:view","document:view_members"]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Document member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Document Iam Org Org Id Project Project Id Document Document Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Documents"],"summary":"IAM - Update Document Member","description":"Update the roles that a member holds on the document.","operationId":"document_iam_org_org_id_project_project_id_document_document_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:view"]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Document member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Document Iam Org Org Id Project Project Id Document Document Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Document Iam Org Org Id Project Project Id Document Document Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/document/{document_id}/iam/test":{"post":{"tags":["Documents"],"summary":"IAM - Test Document Permissions","description":"Test the permissions that the caller (or another subject) holds on the document.","operationId":"document_iam_org_org_id_project_project_id_document_document_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["document:view"]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Document Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Document permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Document Iam Org Org Id Project Project Id Document Document Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Document Iam Org Org Id Project Project Id Document Document Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/integration/catalog":{"get":{"tags":["Integrations"],"summary":"Get Integration Catalog","operationId":"getIntegrationCatalog","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Catalog retrieved","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationCatalogItemRead"},"title":"Response Getintegrationcatalog"},"example":[{"type":"google_sheets","name":"Google Sheets","description":"Read and update spreadsheets, worksheets, and cell ranges.","connection_scopes":["project_default","user"],"credential_policies":["invoker","project_default"],"available_tools":[{"name":"sheets_spreadsheets_batch_update","description":"Applies one or more updates to the spreadsheet.","default_selected":true},{"name":"sheets_spreadsheets_create","description":"Creates a spreadsheet, returning the newly created spreadsheet.","default_selected":true},{"name":"sheets_spreadsheets_get","description":"Returns the spreadsheet at the given ID.","default_selected":true},{"name":"sheets_spreadsheets_values_append","description":"Append one or more rows to a Google Sheets table. Use this for adding new rows, not overwriting existing cells or changing formatting.","default_selected":true},{"name":"sheets_spreadsheets_values_get","description":"Returns a range of values from a spreadsheet.","default_selected":true},{"name":"sheets_spreadsheets_values_update","description":"Sets values in a range of a spreadsheet.","default_selected":true}],"setup_instructions":"Connect Google Sheets for shared project access or let each invoking user connect their own account."},{"type":"slack","name":"Slack","description":"List Slack channels and post messages from TaskAgents.","connection_scopes":["project_default"],"credential_policies":["project_default"],"available_tools":[{"name":"slack_conversations_list","description":"List public and private Slack channels visible to the connected bot.","default_selected":true},{"name":"slack_chat_post_message","description":"Post a message to a Slack channel after validating the channel ID or name.","default_selected":true},{"name":"slack_chat_post_rich_message","description":"Post a structured message to a Slack channel. Use facts for labelled values, tables for repeated records, notices for status, Markdown for narrative, and sources only for verified links. Keep summary_text concise and do not repeat it in the body.","default_selected":false}],"setup_instructions":"Connect Slack so agents can list channels and post messages through the project bot installation."},{"type":"xero","name":"Xero","description":"Find and create contacts, inspect accounting reference data, and create invoices, repeating invoices, and manual journals.","connection_scopes":["project_default"],"credential_policies":["project_default"],"available_tools":[{"name":"xero_contacts_search","description":"Search Xero contacts by name, email, or contact number and return compact identity details.","default_selected":true},{"name":"xero_invoice_reference_list","description":"List one compact Xero accounting reference resource: accounts, tax rates, tracking options, branding themes, or currencies.","default_selected":true},{"name":"xero_contact_create","description":"Create one Xero contact. Search contacts first when creating a duplicate would be undesirable.","default_selected":false},{"name":"xero_invoice_create","description":"Create one draft Xero sales invoice.","default_selected":false},{"name":"xero_repeating_invoice_create","description":"Create one active Xero repeating accounts-receivable invoice template whose generated invoices remain drafts with automatic sending disabled.","default_selected":false},{"name":"xero_manual_journal_create","description":"Create one draft Xero manual journal. If account codes are unknown, call xero_invoice_reference_list with resource='accounts'. Use active non-bank, non-system accounts; positive amounts are debits, negative amounts are credits, and lines must balance to zero.","default_selected":false}],"setup_instructions":"Connect one Xero organisation to share its accounting connection with Tasks and TaskAgents in this project."}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getintegrationcatalog"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"List platform integrations available to create in this workspace."}},"/org/{org_id}/project/{project_id}/integration":{"post":{"tags":["Integrations"],"summary":"Create Integration","operationId":"createIntegration","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectIntegrationCreate"},"examples":{"google_sheets":{"summary":"Google Sheets","value":{"type":"google_sheets"}},"slack":{"summary":"Slack","value":{"type":"slack","config":{"slack_installation_id":"019f8a04-5e54-7002-9f5e-6e9031824042"}}},"xero":{"summary":"Xero","value":{"type":"xero"}}}}}},"responses":{"201":{"description":"Integration created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectIntegrationRead"},"examples":{"Google Sheets":{"summary":"Google Sheets","value":{"id":"019f8a04-5e54-7001-9f5e-6e9031824041","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","type":"slack","name":"Slack","tools":[{"id":"019f8a04-5e54-7003-9f5e-6e9031824043","name":"slack_chat_post_message","description":"Post a message to a Slack channel after validating the channel ID or name.","tool_name":"slack_chat_post_message","tool_description":"Post a message to a Slack channel after validating the channel ID or name.","tool_input_schema":{"type":"object","properties":{"channel_id":{"type":"string","description":"Slack channel ID. Provide exactly one of channel_id or channel_name."},"channel_name":{"type":"string","description":"Slack channel name without #. Provide exactly one of channel_id or channel_name."},"text":{"type":"string","description":"Message text to post."},"thread_ts":{"type":"string","description":"Optional thread timestamp to reply in a thread."},"mrkdwn":{"type":"boolean","description":"Whether Slack mrkdwn formatting is enabled. Defaults to true."}},"required":["text"]},"safe_tool_name":"slack_chat_post_message","enabled":true,"default_selected":true,"created":"2026-05-10T10:00:00Z","modified":"2026-05-10T10:00:00Z"}],"setup_instructions":"Connect Slack so agents can list channels and post messages through the project bot installation.","created":"2026-05-10T10:00:00Z","modified":"2026-05-10T10:00:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createintegration"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to create integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a new platform integration for the project and persist its discovered tools."},"get":{"tags":["Integrations"],"summary":"List Integrations","operationId":"listIntegrations","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"include_disabled_tools","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Disabled Tools"},"description":"Include disabled integration tools in the response. Disabled tools cannot be used at runtime."}],"responses":{"200":{"description":"Integrations retrieved","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProjectIntegrationRead"},"title":"Response Listintegrations"},"example":[{"id":"019f8a04-5e54-7001-9f5e-6e9031824041","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","type":"slack","name":"Slack","tools":[{"id":"019f8a04-5e54-7003-9f5e-6e9031824043","name":"slack_chat_post_message","description":"Post a message to a Slack channel after validating the channel ID or name.","tool_name":"slack_chat_post_message","tool_description":"Post a message to a Slack channel after validating the channel ID or name.","tool_input_schema":{"type":"object","properties":{"channel_id":{"type":"string","description":"Slack channel ID. Provide exactly one of channel_id or channel_name."},"channel_name":{"type":"string","description":"Slack channel name without #. Provide exactly one of channel_id or channel_name."},"text":{"type":"string","description":"Message text to post."},"thread_ts":{"type":"string","description":"Optional thread timestamp to reply in a thread."},"mrkdwn":{"type":"boolean","description":"Whether Slack mrkdwn formatting is enabled. Defaults to true."}},"required":["text"]},"safe_tool_name":"slack_chat_post_message","enabled":true,"default_selected":true,"created":"2026-05-10T10:00:00Z","modified":"2026-05-10T10:00:00Z"}],"setup_instructions":"Connect Slack so agents can list channels and post messages through the project bot installation.","created":"2026-05-10T10:00:00Z","modified":"2026-05-10T10:00:00Z"},{"id":"019f8a04-5e54-7004-9f5e-6e9031824044","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","type":"google_sheets","name":"Google Sheets","tools":[{"id":"019f8a04-5e54-7005-9f5e-6e9031824045","name":"sheets_spreadsheets_values_append","description":"Append one or more rows to a Google Sheets table. Use this for adding new rows, not overwriting existing cells or changing formatting.","tool_name":"sheets_spreadsheets_values_append","tool_description":"Append one or more rows to a Google Sheets table. Use this for adding new rows, not overwriting existing cells or changing formatting.","tool_input_schema":{"type":"object","properties":{"spreadsheet_id":{"type":"string","description":"The target spreadsheet ID."},"range":{"type":"string","description":"A1 notation table-search range. Use `A:L` only for the default first sheet. For a specific tab, use its exact title, for example `'All Transcripts'!A:L`."},"value_input_option":{"type":"string","enum":["RAW","USER_ENTERED"],"description":"How input values are interpreted. Prefer USER_ENTERED for normal spreadsheet entry."},"values":{"type":"array","description":"Rows to append as a 2D array.","items":{"type":"array","items":{"type":"string"}}},"major_dimension":{"type":"string","enum":["ROWS","COLUMNS"],"description":"Use ROWS unless intentionally appending columns."}},"required":["spreadsheet_id","range","value_input_option","values"]},"safe_tool_name":"sheets_spreadsheets_values_append","enabled":true,"default_selected":true,"created":"2026-06-02T09:00:00Z","modified":"2026-06-02T09:00:00Z"}],"setup_instructions":"Connect Google Sheets for shared project access or let each invoking user connect their own account.","created":"2026-06-02T09:00:00Z","modified":"2026-06-02T09:00:00Z"}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listintegrations"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"List platform integrations configured for the project. Disabled tools are excluded by default and can be included for management interfaces."}},"/org/{org_id}/project/{project_id}/integration/{integration_id}":{"get":{"tags":["Integrations"],"summary":"Get Integration","operationId":"getIntegration","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"include_disabled_tools","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Disabled Tools"},"description":"Include disabled integration tools in the response. Disabled tools cannot be used at runtime."}],"responses":{"200":{"description":"Integration retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectIntegrationRead"},"example":{"id":"019f8a04-5e54-7001-9f5e-6e9031824041","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","type":"slack","name":"Slack","tools":[{"id":"019f8a04-5e54-7003-9f5e-6e9031824043","name":"slack_chat_post_message","description":"Post a message to a Slack channel after validating the channel ID or name.","tool_name":"slack_chat_post_message","tool_description":"Post a message to a Slack channel after validating the channel ID or name.","tool_input_schema":{"type":"object","properties":{"channel_id":{"type":"string","description":"Slack channel ID. Provide exactly one of channel_id or channel_name."},"channel_name":{"type":"string","description":"Slack channel name without #. Provide exactly one of channel_id or channel_name."},"text":{"type":"string","description":"Message text to post."},"thread_ts":{"type":"string","description":"Optional thread timestamp to reply in a thread."},"mrkdwn":{"type":"boolean","description":"Whether Slack mrkdwn formatting is enabled. Defaults to true."}},"required":["text"]},"safe_tool_name":"slack_chat_post_message","enabled":true,"default_selected":true,"created":"2026-05-10T10:00:00Z","modified":"2026-05-10T10:00:00Z"}],"setup_instructions":"Connect Slack so agents can list channels and post messages through the project bot installation.","created":"2026-05-10T10:00:00Z","modified":"2026-05-10T10:00:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getintegration"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project_integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project_integration","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project_integration\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project_integration belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"integration","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Retrieve a project integration, including persisted tools and setup guidance. Disabled tools are excluded by default and can be included for management interfaces."},"delete":{"tags":["Integrations"],"summary":"Delete Integration","operationId":"deleteIntegration","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:delete"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"204":{"description":"Integration deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deleteintegration"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have delete permission on project_integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project_integration","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"delete"}}}}},"description":"Forbidden - Insufficient permissions for project_integration\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project_integration belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"integration","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"409":{"description":"Integration has dependent resources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"code":"TASK_REVISIONS_DEPEND_ON_INTEGRATION_TOOLS","message":"Task or TaskAgent revisions reference this integration. Remove those Integration assignments before deleting the integration."}}}}}},"description":"Delete a platform integration and its persisted auth/tool metadata."}},"/org/{org_id}/project/{project_id}/integration/{integration_id}/connections/{connection_scope}/authorize":{"post":{"tags":["Integrations"],"summary":"Authorize Integration Connection","operationId":"authorizeIntegrationConnection","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"connection_scope","in":"path","required":true,"schema":{"$ref":"#/components/schemas/IntegrationConnectionScope"},"description":"Connection ownership scope to administer."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"redirect_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect To"},"description":"Optional console URL to redirect back to after OAuth completes."}],"responses":{"307":{"description":"Redirect to the provider OAuth authorization endpoint","headers":{"Location":{"description":"URL of the provider OAuth authorization endpoint","schema":{"type":"string","format":"uri"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Authorizeintegrationconnection"},"examples":{"project_integration_view":{"summary":"Missing view on project_integration","value":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project_integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project_integration","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}},"project_integration_edit":{"summary":"Missing edit on project_integration","value":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project_integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project_integration","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}}}},"description":"Forbidden - insufficient permission for this operation"},"422":{"description":"Unprocessable Entity - Invalid connection scope\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_validation":{"summary":"Request validation failed","value":{"detail":[{"loc":["body"],"msg":"Invalid connection scope","type":"value_error"}]}},"domain_validation":{"summary":"Domain precondition failed","value":{"detail":"The provider does not support this connection scope."}}}}}},"303":{"description":"Redirect to a provider OAuth endpoint using GET","headers":{"Location":{"description":"URL of the provider OAuth authorization endpoint","schema":{"type":"string","format":"uri"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"integration","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Start the provider-specific OAuth flow. Xero connects exactly one organisation as the shared project-default connection. Managing your own user-scoped connection requires view permission; managing a shared project-default connection requires edit permission."}},"/org/{org_id}/project/{project_id}/integration/{integration_id}/connections/{connection_scope}":{"get":{"tags":["Integrations"],"summary":"Get Integration Connection","operationId":"getIntegrationConnection","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"connection_scope","in":"path","required":true,"schema":{"$ref":"#/components/schemas/IntegrationConnectionScope"},"description":"Connection ownership scope to administer."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Integration auth status retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationConnectionStatusRead"},"examples":{"connected":{"summary":"Connected","value":{"integration_id":"019f8a04-5e54-7004-9f5e-6e9031824044","connection_scope":"project_default","connection":{"id":"019f8a04-5e54-7006-9f5e-6e9031824046","auth_state":"connected","auth_state_reason":null,"connected_by_user_id":"019f8a00-1a10-7003-8b1a-2a5c9d4e0003","created":"2026-06-02T09:05:00Z","modified":"2026-06-02T09:05:00Z"}}},"disconnected":{"summary":"Disconnected","value":{"integration_id":"019f8a04-5e54-7004-9f5e-6e9031824044","connection_scope":"project_default","connection":{"id":"019f8a04-5e54-7006-9f5e-6e9031824046","auth_state":"disconnected","auth_state_reason":null,"connected_by_user_id":"019f8a00-1a10-7003-8b1a-2a5c9d4e0003","created":"2026-06-02T09:05:00Z","modified":"2026-07-22T11:40:00Z"}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getintegrationconnection"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project_integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project_integration","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project_integration\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project_integration belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid connection scope\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_validation":{"summary":"Request validation failed","value":{"detail":[{"loc":["body"],"msg":"Invalid connection scope","type":"value_error"}]}},"domain_validation":{"summary":"Domain precondition failed","value":{"detail":"The provider does not support this connection scope."}}}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"integration","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Get connection state for the requested ownership scope. A user connection always belongs to the authenticated caller."}},"/org/{org_id}/project/{project_id}/integration/{integration_id}/connections/{connection_scope}/disconnect":{"post":{"tags":["Integrations"],"summary":"Disconnect Integration Connection","operationId":"disconnectIntegrationConnection","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"connection_scope","in":"path","required":true,"schema":{"$ref":"#/components/schemas/IntegrationConnectionScope"},"description":"Connection ownership scope to administer."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"force","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Force"},"description":"Disconnect a project-default connection even when active Tasks or TaskAgents depend on it. Not applicable to user connections."}],"responses":{"200":{"description":"Integration disconnected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationConnectionStatusRead"},"example":{"integration_id":"019f8a04-5e54-7004-9f5e-6e9031824044","connection_scope":"project_default","connection":{"id":"019f8a04-5e54-7006-9f5e-6e9031824046","auth_state":"disconnected","auth_state_reason":null,"connected_by_user_id":"019f8a00-1a10-7003-8b1a-2a5c9d4e0003","created":"2026-06-02T09:05:00Z","modified":"2026-07-22T11:40:00Z"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Disconnectintegrationconnection"},"examples":{"project_integration_view":{"summary":"Missing view on project_integration","value":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project_integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project_integration","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}},"project_integration_edit":{"summary":"Missing edit on project_integration","value":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project_integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project_integration","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}}}},"description":"Forbidden - insufficient permission for this operation"},"422":{"description":"Unprocessable Entity - Invalid connection scope\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_validation":{"summary":"Request validation failed","value":{"detail":[{"loc":["body"],"msg":"Invalid connection scope","type":"value_error"}]}},"domain_validation":{"summary":"Domain precondition failed","value":{"detail":"The provider does not support this connection scope."}}}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find integration [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"integration","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"409":{"description":"Conflict - Integration connection already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"code":"integration_connection_in_use","message":"The project-default connection is used by active configurations.","task_count":2,"task_agent_count":1}}}}}},"description":"Disconnect the active connection. Managing your own user-scoped connection requires view permission; managing a shared project-default connection requires edit permission."}},"/org/{org_id}/project/{project_id}/integration/{integration_id}/iam/members":{"get":{"tags":["Integrations"],"summary":"IAM - List Project Integration Members","description":"Lists all members that have been granted direct access to the project_integration.","operationId":"project_integration_iam_org_org_id_project_project_id_integration_integration_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view","project_integration:view_members"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Project Integration members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Integration Iam Org Org Id Project Project Id Integration Integration Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/integration/{integration_id}/iam/members/{member}":{"get":{"tags":["Integrations"],"summary":"IAM - Lookup Project Integration Member","description":"Retrieve a specific member that has been granted direct access to the project_integration.","operationId":"project_integration_iam_org_org_id_project_project_id_integration_integration_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view","project_integration:view_members"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Project Integration member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Integration Iam Org Org Id Project Project Id Integration Integration Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Integrations"],"summary":"IAM - Update Project Integration Member","description":"Update the roles that a member holds on the project_integration.","operationId":"project_integration_iam_org_org_id_project_project_id_integration_integration_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project_IntegrationIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Project Integration member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Project Integration Iam Org Org Id Project Project Id Integration Integration Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Integration Iam Org Org Id Project Project Id Integration Integration Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/integration/{integration_id}/iam/test":{"post":{"tags":["Integrations"],"summary":"IAM - Test Project Integration Permissions","description":"Test the permissions that the caller (or another subject) holds on the project_integration.","operationId":"project_integration_iam_org_org_id_project_project_id_integration_integration_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project_IntegrationIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Project Integration permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Project Integration Iam Org Org Id Project Project Id Integration Integration Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Integration Iam Org Org Id Project Project Id Integration Integration Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/mcp_server":{"get":{"tags":["MCP Servers"],"summary":"List MCP Servers","description":"List all MCP servers configured for the project.\n\nReturns a paginated list of MCP servers with their:\n- Root URL\n- Sync status\n- Creation and modification timestamps\n\nUse pagination parameters to navigate through large result sets.","operationId":"listMcpServers","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor returned from a previous request. Use this to fetch the next page of results.","schema":{"type":"string","format":"uuid"},"example":"0190a234-8dc6-6d08-aea9-928fcecad8f1"},{"name":"page_limit","in":"query","required":false,"description":"Number of results per page","schema":{"type":"integer","default":100,"minimum":1,"maximum":1000}}],"responses":{"200":{"description":"Successfully retrieved MCP servers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_McpServer_"},"examples":{"multiple_servers":{"summary":"Multiple MCP Servers","value":{"results":[{"id":"0197a8c1-2b4c-7a91-8e3d-4f5a6b7c8d9e","short_id":"a8c12b4c","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"acme-analytics-postgres","description":"Read-only MCP access to the analytics warehouse for reporting queries.","url":"https://analytics-mcp.acme-logistics.com","syncd":true,"created":"2026-06-02T09:15:00Z","modified":"2026-06-02T09:15:00Z"},{"id":"0197b2d3-3c5d-7b02-9f4e-5a6b7c8d9e0f","short_id":"b2d33c5d","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"acme-support-tickets","description":"MCP access to the support ticketing system for triage automation.","url":"https://tickets-mcp.acme-logistics.com","syncd":true,"created":"2026-06-10T14:30:00Z","modified":"2026-06-10T14:30:00Z"}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid pagination"}}},"description":"Bad Request - Invalid pagination\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listmcpservers"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve MCP servers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"post":{"tags":["MCP Servers"],"summary":"Create MCP Server","description":"Register a new MCP server for the project.\n\nMCP servers extend AI capabilities by providing access to external tools over\nthe Model Context Protocol. Common examples include:\n- Database or analytics servers exposing read-only query tools\n- Ticketing or CRM integrations\n- Internal wiki or knowledge-base lookup\n\nRegistration only requires the server's root URL, which must be a root URL\nwithout path components; the server is not synchronized yet when this call\nreturns (`syncd: false`) and must be marked synced afterward to discover its\navailable tools.","operationId":"createMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_mcp_server"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServerCreate"},"examples":{"analytics_postgres":{"summary":"Analytics Database Server","value":{"name":"acme-analytics-postgres","description":"Read-only MCP access to the analytics warehouse for reporting queries.","url":"https://analytics-mcp.acme-logistics.com"}},"company_wiki":{"summary":"Company Wiki Server","value":{"name":"acme-company-wiki","description":"MCP access to the internal company wiki for knowledge lookup.","url":"https://wiki-mcp.acme-logistics.com"}}}}}},"responses":{"200":{"description":"MCP server registered (not yet synchronized)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServer"},"examples":{"Analytics Database Server":{"summary":"Analytics Database Server","value":{"id":"0198c1e4-4d6e-7c13-a05f-6b7c8d9e0f10","short_id":"c1e44d6e","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"acme-company-wiki","description":"MCP access to the internal company wiki for knowledge lookup.","url":"https://wiki-mcp.acme-logistics.com","syncd":false,"created":"2026-07-01T11:00:00Z","modified":"2026-07-01T11:00:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid configuration"}}},"description":"Bad Request - Invalid configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createmcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_mcp_server permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_mcp_server"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to create MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/mcp_server/{mcp_server_id}":{"get":{"tags":["MCP Servers"],"summary":"Get MCP Server","description":"Retrieve detailed information about a specific MCP server.\n\nReturns the server's configuration, sync status, and creation/modification\ntimestamps.","operationId":"getMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:view"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"MCP server details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServer"},"example":{"id":"0197a8c1-2b4c-7a91-8e3d-4f5a6b7c8d9e","short_id":"a8c12b4c","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"acme-analytics-postgres","description":"Read-only MCP access to the analytics warehouse for reporting queries.","url":"https://analytics-mcp.acme-logistics.com","syncd":true,"created":"2026-06-02T09:15:00Z","modified":"2026-06-02T09:15:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getmcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"mcp_server","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"post":{"tags":["MCP Servers"],"summary":"Update MCP Server","description":"Update MCP server configuration.\n\nModifiable fields:\n- Name and description\n- Root URL\n\nNote: Updating the root URL may trigger re-synchronization.","operationId":"updateMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:edit"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServerUpdate"},"examples":{"update_url":{"summary":"Update Root URL","value":{"url":"https://analytics-mcp-v2.acme-logistics.com"}}}}}},"responses":{"200":{"description":"MCP server updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServer"},"examples":{"Update Root URL":{"summary":"Update Root URL","value":{"id":"0197a8c1-2b4c-7a91-8e3d-4f5a6b7c8d9e","short_id":"a8c12b4c","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"acme-analytics-postgres","description":"Read-only MCP access to the analytics warehouse for reporting queries.","url":"https://analytics-mcp-v2.acme-logistics.com","syncd":true,"created":"2026-06-02T09:15:00Z","modified":"2026-07-15T10:05:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid configuration"}}},"description":"Bad Request - Invalid configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatemcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"mcp_server","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to update MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"delete":{"tags":["MCP Servers"],"summary":"Delete MCP Server","description":"Remove an MCP server from the project.\n\nThis will:\n- Stop any active connections\n- Remove server configuration\n- Delete execution history\n\nThis action cannot be undone.","operationId":"deleteMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:edit"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"MCP server deleted","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]},"example":{"detail":"MCP server deleted successfully"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletemcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"mcp_server","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to delete MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/mcp_server/{mcp_server_id}/sync":{"post":{"tags":["MCP Servers"],"summary":"Mark MCP Server Synced","description":"Mark an MCP server as synchronized after successful tool discovery.\n\nThis endpoint updates the sync status and timestamp. It requires `edit`\npermission on the MCP server, the same as `updateMcpServer`.","operationId":"markMcpServerSynced","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:edit"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Server marked as synced","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServer"},"example":{"id":"0198c1e4-4d6e-7c13-a05f-6b7c8d9e0f10","short_id":"c1e44d6e","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"acme-company-wiki","description":"MCP access to the internal company wiki for knowledge lookup.","url":"https://wiki-mcp.acme-logistics.com","syncd":true,"created":"2026-07-01T11:00:00Z","modified":"2026-07-01T11:03:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Markmcpserversynced"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"mcp_server","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to update sync status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/mcp_server/{mcp_server_id}/iam/members":{"get":{"tags":["MCP Servers"],"summary":"IAM - List Mcp Server Members","description":"Lists all members that have been granted direct access to the mcp_server.","operationId":"mcp_server_iam_org_org_id_project_project_id_mcp_server_mcp_server_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:view","mcp_server:view_members"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mcp Server Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Mcp Server members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Mcp Server Iam Org Org Id Project Project Id Mcp Server Mcp Server Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/mcp_server/{mcp_server_id}/iam/members/{member}":{"get":{"tags":["MCP Servers"],"summary":"IAM - Lookup Mcp Server Member","description":"Retrieve a specific member that has been granted direct access to the mcp_server.","operationId":"mcp_server_iam_org_org_id_project_project_id_mcp_server_mcp_server_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:view","mcp_server:view_members"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mcp Server Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Mcp Server member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Mcp Server Iam Org Org Id Project Project Id Mcp Server Mcp Server Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["MCP Servers"],"summary":"IAM - Update Mcp Server Member","description":"Update the roles that a member holds on the mcp_server.","operationId":"mcp_server_iam_org_org_id_project_project_id_mcp_server_mcp_server_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:view"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mcp Server Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mcp_ServerIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Mcp Server member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Mcp Server Iam Org Org Id Project Project Id Mcp Server Mcp Server Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Mcp Server Iam Org Org Id Project Project Id Mcp Server Mcp Server Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/mcp_server/{mcp_server_id}/iam/test":{"post":{"tags":["MCP Servers"],"summary":"IAM - Test Mcp Server Permissions","description":"Test the permissions that the caller (or another subject) holds on the mcp_server.","operationId":"mcp_server_iam_org_org_id_project_project_id_mcp_server_mcp_server_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:view"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mcp_ServerIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Mcp Server permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Mcp Server Iam Org Org Id Project Project Id Mcp Server Mcp Server Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Mcp Server Iam Org Org Id Project Project Id Mcp Server Mcp Server Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/mcp_server/{mcp_server_id}/mcp_run":{"get":{"tags":["MCP Runs"],"summary":"List MCP Run History","description":"Retrieve execution history for an MCP server.\n\nLists all tool invocations made through the specified MCP server, including:\n- MCP method and JSON-RPC request ID\n- Request and response payloads\n- Duration in milliseconds\n- Whether the run was a server-sent event\n\nUseful for:\n- Debugging tool interactions\n- Monitoring usage patterns\n- Auditing external system access\n- Performance optimization","operationId":"listMcpRuns","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:view"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"description":"The UUID of the MCP server","schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"page_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"method","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Method"},"description":"Filter by MCP methods (can specify multiple)"},{"name":"sse_event","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Sse Event"},"description":"Filter by server-sent event flag"}],"responses":{"200":{"description":"Successfully retrieved MCP run history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_McpRun_"},"examples":{"recent_runs":{"summary":"Recent Runs","value":{"results":[{"id":"01990829-9213-7168-95a4-bf2a3b4c5d6f","mcp_server_id":"0197a8c1-2b4c-7a91-8e3d-4f5a6b7c8d9e","method":"tools/call","request_id":"2","protocol_version":"2025-06-18","request":{"name":"query_orders_by_status","arguments":{"status":"delayed"}},"response":{"content":[{"type":"text","text":"12 orders are currently delayed."}],"isError":false},"duration_ms":184,"sse_event":false,"created":"2026-07-10T09:01:47Z","modified":"2026-07-10T09:01:47Z"},{"id":"01990718-8102-7057-8493-af1a2b3c4d5e","mcp_server_id":"0197a8c1-2b4c-7a91-8e3d-4f5a6b7c8d9e","method":"tools/list","request_id":"1","protocol_version":"2025-06-18","request":{},"response":{"tools":[{"name":"query_orders_by_status","description":"Return order counts grouped by status for a date range."},{"name":"query_shipment_summary","description":"Summarize shipment volumes by carrier and region."}]},"duration_ms":38,"sse_event":false,"created":"2026-07-10T09:00:12Z","modified":"2026-07-10T09:00:12Z"}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid pagination"}}},"description":"Bad Request - Invalid pagination\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listmcpruns"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"mcp_server","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve MCP runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"post":{"tags":["MCP Runs"],"summary":"Record MCP Run","description":"Record a new MCP tool execution.\n\nThis endpoint is typically called automatically when tools are invoked,\nbut can be used manually for:\n- Custom tool integrations\n- Testing and debugging\n- Simulating tool calls\n- Recording manual operations\n\nThe run record captures the complete interaction for audit and analysis. The\n`mcp_server_id` in the request body must match the `mcp_server_id` path\nparameter.","operationId":"createMcpRun","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:edit"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"description":"The UUID of the MCP server","schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRunCreate"},"examples":{"successful_run":{"summary":"Successful Tool Call","value":{"mcp_server_id":"0197a8c1-2b4c-7a91-8e3d-4f5a6b7c8d9e","method":"tools/call","request_id":"2","protocol_version":"2025-06-18","request":{"name":"query_orders_by_status","arguments":{"status":"delayed"}},"response":{"content":[{"type":"text","text":"12 orders are currently delayed."}],"isError":false},"duration_ms":184,"sse_event":false}},"failed_run":{"summary":"Failed Tool Call","value":{"mcp_server_id":"0197a8c1-2b4c-7a91-8e3d-4f5a6b7c8d9e","method":"tools/call","request_id":"3","protocol_version":"2025-06-18","request":{"name":"query_orders_by_status","arguments":{"status":"archived"}},"response":{"error":{"code":-32602,"message":"Invalid params: unknown status 'archived'"}},"duration_ms":9,"sse_event":false}}}}}},"responses":{"200":{"description":"MCP run created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRun"},"examples":{"Successful Tool Call":{"summary":"Successful Tool Call","value":{"id":"01990829-9213-7168-95a4-bf2a3b4c5d6f","mcp_server_id":"0197a8c1-2b4c-7a91-8e3d-4f5a6b7c8d9e","method":"tools/call","request_id":"2","protocol_version":"2025-06-18","request":{"name":"query_orders_by_status","arguments":{"status":"delayed"}},"response":{"content":[{"type":"text","text":"12 orders are currently delayed."}],"isError":false},"duration_ms":184,"sse_event":false,"created":"2026-07-10T09:01:47Z","modified":"2026-07-10T09:01:47Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid request"}}},"description":"Bad Request - Invalid request\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createmcprun"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"mcp_server","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to execute MCP tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/mcp_server/{mcp_server_id}/mcp_run/{mcp_run_id}":{"get":{"tags":["MCP Runs"],"summary":"Get MCP Run Details","description":"Retrieve detailed information about a specific MCP tool execution.\n\nReturns complete execution details including:\n- Full request parameters\n- Complete response data\n- Duration and server-sent event flag\n\nUseful for debugging specific tool interactions or analyzing complex responses.","operationId":"getMcpRun","security":[{"HTTPBearer":[]},{"HTTPBearer":["mcp_server:view"]}],"parameters":[{"name":"mcp_server_id","in":"path","required":true,"description":"The UUID of the MCP server","schema":{"type":"string","format":"uuid"}},{"name":"mcp_run_id","in":"path","required":true,"description":"The UUID of the MCP run","schema":{"type":"string","format":"uuid"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"MCP run details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpRun"},"examples":{"detailed_run":{"summary":"Detailed Run Information","value":{"id":"01990829-9213-7168-95a4-bf2a3b4c5d6f","mcp_server_id":"0197a8c1-2b4c-7a91-8e3d-4f5a6b7c8d9e","method":"tools/call","request_id":"2","protocol_version":"2025-06-18","request":{"name":"query_orders_by_status","arguments":{"status":"delayed"}},"response":{"content":[{"type":"text","text":"12 orders are currently delayed."}],"isError":false},"duration_ms":184,"sse_event":false,"created":"2026-07-10T09:01:47Z","modified":"2026-07-10T09:01:47Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid UUID format"}}},"description":"Bad Request - Invalid UUID format\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getmcprun"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find mcp_run [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"mcp_run","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve MCP run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/scrape":{"post":{"tags":["Scrape"],"summary":"Enable Web Scrape","operationId":"enableWebScrape","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Enablewebscrape"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/scrape/start":{"post":{"tags":["Scrape"],"summary":"Initialise Web Scrape","operationId":"startWebScrape","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteScrapeRequest"},"example":{"urls":["https://docs.rightbrain.ai/"],"max_crawl_depth":3}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasourceSyncRun"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Startwebscrape"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Start a web-scrape synchronization run for one or more HTTP or HTTPS URLs. The crawl depth defaults to 3 and cannot exceed 7.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/scrape/run/{sync_run_id}":{"get":{"tags":["Scrape"],"summary":"Check Scraping Status","operationId":"checkScrapeStatus","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"sync_run_id","in":"path","required":true,"description":"The UUID of the scraping job (the `id` returned by `POST /scrape/start`)","schema":{"type":"string"},"example":"019662a1-4b8e-7c3a-9f21-3e8b7c9d1a02"}],"responses":{"200":{"description":"Scraping job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasourceSyncRun"},"examples":{"in_progress":{"summary":"In Progress","value":{"id":"019662a1-4b8e-7c3a-9f21-3e8b7c9d1a02","created":"2026-01-20T10:30:00Z","modified":"2026-01-20T10:45:00Z","task_id":"6f2c1e3a-7b9d-4a5e-8f10-2d3c4b5a6e70","status":"started","run_output":{}}},"success":{"summary":"Success","value":{"id":"019662a1-4b8e-7c3a-9f21-3e8b7c9d1a02","created":"2026-01-20T10:30:00Z","modified":"2026-01-20T11:15:00Z","task_id":"6f2c1e3a-7b9d-4a5e-8f10-2d3c4b5a6e70","status":"success","run_output":{}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Checkscrapestatus"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"No scraping job with that ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find datasource_sync_runs [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"datasource_sync_runs","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Check the status of a web scraping job.\n\nReturns the `DatasourceSyncRun` record for the job: its lifecycle `status`\n(`pending`, `started`, `success`, `failure`, `retry`, or `progress`), the Celery\n`task_id` backing it, a free-form `run_output` populated by the background worker,\nand the `datasource_connection` it belongs to.\n\nUse this to monitor long-running scraping operations.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/scrape/runs":{"get":{"tags":["Scrape"],"summary":"List Scraping History","operationId":"listScrapeRuns","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}},{"name":"cursor","in":"query","required":false,"description":"Pagination cursor","schema":{"type":"string"}},{"name":"page_limit","in":"query","required":false,"description":"Results per page","schema":{"type":"integer","default":25}}],"responses":{"200":{"description":"Paginated scraping job history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_DatasourceSyncRun_"},"example":{"pagination":{"has_next":false,"page_limit":25},"results":[{"id":"019662a1-4b8e-7c3a-9f21-3e8b7c9d1a02","created":"2026-01-20T10:30:00Z","modified":"2026-01-20T11:15:00Z","task_id":"6f2c1e3a-7b9d-4a5e-8f10-2d3c4b5a6e70","status":"success","run_output":{}}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listscraperuns"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"412":{"description":"Web scraping has not been enabled for this project - call `POST /scrape` first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"DATASOURCE_NOT_CONFIGURED","message":"web_scrape datasource not enabled","datasourceNotConfiguredError":{"datasource":"web_scrape"}}}}}}},"description":"List all web scraping jobs for the project's web-scrape datasource connection.\n\nReturns the paginated `DatasourceSyncRun` history - each entry's lifecycle `status`,\nCelery `task_id`, and `run_output`.\n\nUseful for tracking scraping activity and managing content sources.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/compose":{"post":{"tags":["Compose"],"summary":"Initialize Compose Session","operationId":"initializeCompose","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_compose"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComposeInit"},"examples":{"case_study_brief":{"summary":"Case Study, Minimal Brief","value":{"title":"How Solstice Freight Cut Warehouse Putaway Time by 32%","topic":"warehouse putaway automation for mid-market logistics operators","tone":"confident and data-driven"}},"case_study_detailed":{"summary":"Case Study, Detailed Brief","value":{"title":"How Solstice Freight Cut Warehouse Putaway Time by 32%","topic":"warehouse putaway automation for mid-market logistics operators","purpose":"Persuade operations directors evaluating warehouse workflow software that structured putaway rules cut cycle time without adding headcount","audience":"operations directors and warehouse managers at mid-market 3PLs","num_sections":5,"word_count":900,"voice":"third person","domain":"logistics and supply chain operations","tone":"confident, data-driven, conversational","keywords":"warehouse putaway, dock-to-stock time, logistics automation","cta":"Book a 20-minute workflow review with our operations team","language":"english_british"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Initializecompose"}},"application/x-ndjson":{"schema":{"type":"string"},"examples":{"Case Study, Minimal Brief":{"summary":"Case Study, Minimal Brief","value":"{\"token\": \"```\"}\n{\"token\": \"json\"}\n{\"token\": \"\\n\"}\n{\"token\": \"[\\n\"}\n{\"token\": \"  {\\n\"}\n{\"token\": \"    \\\"position\\\": 1,\\n\"}\n{\"token\": \"    \\\"title\\\": \\\"Introduction\\\"\\n\"}\n{\"token\": \"  },\\n\"}\n{\"token\": \"  {\\n\"}\n{\"token\": \"    \\\"position\\\": 2,\\n\"}\n{\"token\": \"    \\\"title\\\": \\\"The Warehouse Challenge\\\"\\n\"}\n{\"token\": \"  },\\n\"}\n{\"token\": \"  {\\n\"}\n{\"token\": \"    \\\"position\\\": 3,\\n\"}\n{\"token\": \"    \\\"title\\\": \\\"Rolling Out Structured Putaway\\\"\\n\"}\n{\"token\": \"  },\\n\"}\n{\"token\": \"  {\\n\"}\n{\"token\": \"    \\\"position\\\": 4,\\n\"}\n{\"token\": \"    \\\"title\\\": \\\"Results After 90 Days\\\"\\n\"}\n{\"token\": \"  },\\n\"}\n{\"token\": \"  {\\n\"}\n{\"token\": \"    \\\"position\\\": 5,\\n\"}\n{\"token\": \"    \\\"title\\\": \\\"Getting Started\\\"\\n\"}\n{\"token\": \"  }\\n\"}\n{\"token\": \"]\\n\"}\n{\"token\": \"```\"}"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Initializecompose"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"org_id","in":"path","required":true,"description":"The UUID of the organization","schema":{"type":"string","format":"uuid"}},{"name":"project_id","in":"path","required":true,"description":"The UUID of the project","schema":{"type":"string","format":"uuid"}}],"description":"Initialize a new compose session for AI-assisted document creation.\n\nSets up the context for generating structured content including:\n- Document type and format preferences\n- Target audience and tone\n- Initial outline or structure\n- Any reference materials or context\n\nThis endpoint prepares the AI to assist with content generation tailored to your needs.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/compose/generate":{"post":{"tags":["Compose"],"summary":"Generate Content","operationId":"generateContent","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_compose"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_generateContent"},"examples":{"full_structure":{"summary":"Generate The Full Outline","value":{"compose":{"structure":[{"position":1,"title":"Introduction","ideas":["open with the pain of inconsistent putaway across sites","introduce Solstice Freight and its three regional distribution centres"]},{"position":2,"title":"The Warehouse Challenge","ideas":["describe inconsistent putaway rules across three DCs","cite Q3 outbound pallet volume of 42,000 pallets","explain how misrouted stock delayed replenishment"]},{"position":3,"title":"Rolling Out Structured Putaway","ideas":["introduce zone-based putaway logic tied to SKU velocity","describe the phased two-week training rollout"]},{"position":4,"title":"Results After 90 Days","ideas":["putaway cycle time down from 14 to 9.5 minutes per pallet","dock-to-stock variance narrowed to under 45 minutes"]},{"position":5,"title":"Getting Started","ideas":["invite readers to book a workflow review"]}]},"context":{"title":"How Solstice Freight Cut Warehouse Putaway Time by 32%","topic":"warehouse putaway automation for mid-market logistics operators","purpose":"Persuade operations directors evaluating warehouse workflow software that structured putaway rules cut cycle time without adding headcount","audience":"operations directors and warehouse managers at mid-market 3PLs","num_sections":5,"word_count":900,"voice":"third person","domain":"logistics and supply chain operations","tone":"confident, data-driven, conversational","keywords":"warehouse putaway, dock-to-stock time, logistics automation","cta":"Book a 20-minute workflow review with our operations team","language":"english_british"}}},"single_section":{"summary":"Generate One Section","value":{"compose":{"structure":[{"position":2,"title":"The Warehouse Challenge","ideas":["describe inconsistent putaway rules across three DCs","cite Q3 outbound pallet volume of 42,000 pallets","explain how misrouted stock delayed replenishment"]}]},"context":{"title":"How Solstice Freight Cut Warehouse Putaway Time by 32%","topic":"warehouse putaway automation for mid-market logistics operators","purpose":"Persuade operations directors evaluating warehouse workflow software that structured putaway rules cut cycle time without adding headcount","audience":"operations directors and warehouse managers at mid-market 3PLs","num_sections":5,"word_count":900,"voice":"third person","domain":"logistics and supply chain operations","tone":"confident, data-driven, conversational","keywords":"warehouse putaway, dock-to-stock time, logistics automation","cta":"Book a 20-minute workflow review with our operations team","language":"english_british"}}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Generatecontent"}},"application/x-ndjson":{"schema":{"type":"string"},"examples":{"Generate The Full Outline":{"summary":"Generate The Full Outline","value":"{\"token\": \"## Introduction\\n\"}\n{\"token\": \"Solstice Freight runs three regional distribution\"}\n{\"token\": \" centres that together move more than 40,000\"}\n{\"token\": \" pallets a quarter for retail and industrial\"}\n{\"token\": \" customers. Until this year, each site followed\"}\n{\"token\": \" its own putaway habits, and operations leaders\"}\n{\"token\": \" had no consistent way to measure how quickly\"}\n{\"token\": \" inbound stock became sellable inventory.\"}"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Generatecontent"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"org_id","in":"path","required":true,"description":"The UUID of the organization","schema":{"type":"string","format":"uuid"}},{"name":"project_id","in":"path","required":true,"description":"The UUID of the project","schema":{"type":"string","format":"uuid"}}],"description":"Generate content based on the initialized compose session and provided instructions.\n\nThe AI will create content that:\n- Follows the established context and parameters\n- Maintains consistent tone and style\n- Includes relevant examples and details\n- Structures information logically\n\nYou can iteratively refine the generated content through subsequent calls.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/compose/update_section":{"post":{"tags":["Compose"],"summary":"Update Document Section","operationId":"updateSection","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_compose"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_updateSection"},"examples":{"tighten_challenge_paragraph":{"summary":"Tighten A Paragraph And Cite A Figure","value":{"context":{"title":"How Solstice Freight Cut Warehouse Putaway Time by 32%","topic":"warehouse putaway automation for mid-market logistics operators","purpose":"Persuade operations directors evaluating warehouse workflow software that structured putaway rules cut cycle time without adding headcount","audience":"operations directors and warehouse managers at mid-market 3PLs","num_sections":5,"word_count":900,"voice":"third person","domain":"logistics and supply chain operations","tone":"confident, data-driven, conversational","keywords":"warehouse putaway, dock-to-stock time, logistics automation","cta":"Book a 20-minute workflow review with our operations team","language":"english_british"},"existing_content":{"existing_content":"Solstice Freight operates three regional distribution centres, each with its own informal putaway rules that pickers and forklift operators had learned as shortcuts over the years.\n\nNo two shifts stored inbound pallets the same way, and a routine audit found that misrouted stock accounted for nearly a fifth of all replenishment delays across the network, making it difficult to forecast dock-to-stock time or plan labour."},"update_instruction":{"position":2,"section_title":"The Warehouse Challenge","instructions":["Tighten the second paragraph so it reads as two sentences instead of three","Cite the Q3 outbound volume figure of 42,000 pallets to quantify the scale of the problem"],"text":"No two shifts stored inbound pallets the same way, and a routine audit found that misrouted stock accounted for nearly a fifth of all replenishment delays across the network, making it difficult to forecast dock-to-stock time or plan labour."}}},"simplify_results_for_execs":{"summary":"Simplify Jargon For An Exec Audience","value":{"context":{"title":"How Solstice Freight Cut Warehouse Putaway Time by 32%","topic":"warehouse putaway automation for mid-market logistics operators","purpose":"Persuade operations directors evaluating warehouse workflow software that structured putaway rules cut cycle time without adding headcount","audience":"operations directors and warehouse managers at mid-market 3PLs","num_sections":5,"word_count":900,"voice":"third person","domain":"logistics and supply chain operations","tone":"confident, data-driven, conversational","keywords":"warehouse putaway, dock-to-stock time, logistics automation","cta":"Book a 20-minute workflow review with our operations team","language":"english_british"},"existing_content":{"existing_content":"Following the rollout of zone-based putaway logic and barcode-verified slotting, Solstice Freight reduced average putaway cycle time from 14 minutes to 9.5 minutes per pallet, a 32% improvement. Dock-to-stock variance across the three centres narrowed from four hours to under 45 minutes, and mis-slotted pallet exceptions fell by 61% quarter over quarter."},"update_instruction":{"position":4,"section_title":"Results After 90 Days","instructions":["Simplify the phrase 'dock-to-stock variance' for a non-operations executive audience","Keep the 32% putaway time reduction as the headline statistic"]}}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Updatesection"}},"application/x-ndjson":{"schema":{"type":"string"},"examples":{"Tighten A Paragraph And Cite A Figure":{"summary":"Tighten A Paragraph And Cite A Figure","value":"{\"token\": \"No two shifts stored inbound pallets the same\"}\n{\"token\": \" way. Against a Q3 outbound volume of 42,000\"}\n{\"token\": \" pallets, misrouted stock drove nearly a fifth\"}\n{\"token\": \" of all replenishment delays across the network.\"}"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatesection"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"org_id","in":"path","required":true,"description":"The UUID of the organization","schema":{"type":"string","format":"uuid"}},{"name":"project_id","in":"path","required":true,"description":"The UUID of the project","schema":{"type":"string","format":"uuid"}}],"description":"Update or refine a specific section of the generated content.\n\nAllows targeted improvements to:\n- Expand on specific points\n- Adjust tone or complexity\n- Add or remove examples\n- Restructure paragraphs\n- Fix inconsistencies\n\nThe AI maintains context awareness to ensure updates align with the overall document.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/compose/section_talking_points":{"post":{"tags":["Compose"],"summary":"Generate Section Talking Points","operationId":"generateTalkingPoints","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_compose"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Body_generateTalkingPoints"},"examples":{"plan_next_section":{"summary":"Plan The Next Section","value":{"context":{"title":"How Solstice Freight Cut Warehouse Putaway Time by 32%","topic":"warehouse putaway automation for mid-market logistics operators","purpose":"Persuade operations directors evaluating warehouse workflow software that structured putaway rules cut cycle time without adding headcount","audience":"operations directors and warehouse managers at mid-market 3PLs","num_sections":5,"word_count":900,"voice":"third person","domain":"logistics and supply chain operations","tone":"confident, data-driven, conversational","keywords":"warehouse putaway, dock-to-stock time, logistics automation","cta":"Book a 20-minute workflow review with our operations team","language":"english_british"},"existing_content":{"existing_content":"Solstice Freight operates three regional distribution centres, each with its own informal putaway rules that pickers and forklift operators had learned as shortcuts over the years.\n\nNo two shifts stored inbound pallets the same way. Against a Q3 outbound volume of 42,000 pallets, misrouted stock drove nearly a fifth of all replenishment delays across the network."},"update_instruction":{"section_heading":"Rolling Out Structured Putaway"}}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Generatetalkingpoints"}},"application/x-ndjson":{"schema":{"type":"string"},"examples":{"Plan The Next Section":{"summary":"Plan The Next Section","value":"{\"token\": \"```\"}\n{\"token\": \"json\"}\n{\"token\": \"\\n\"}\n{\"token\": \"{\\n\"}\n{\"token\": \"    \\\"position\\\": 3,\\n\"}\n{\"token\": \"    \\\"title\\\": \\\"Rolling Out Structured Putaway\\\",\\n\"}\n{\"token\": \"    \\\"ideas\\\": [\\n\"}\n{\"token\": \"        \\\"Introduced zone-based putaway logic tied to SKU velocity\\\",\\n\"}\n{\"token\": \"        \\\"Trained pickers on barcode-verified slotting over a two-week phased rollout\\\",\\n\"}\n{\"token\": \"        \\\"Ran the new workflow alongside the old one for one shift per site before cutover\\\"\\n\"}\n{\"token\": \"    ]\\n\"}\n{\"token\": \"}\\n\"}\n{\"token\": \"```\"}"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Generatetalkingpoints"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"org_id","in":"path","required":true,"description":"The UUID of the organization","schema":{"type":"string","format":"uuid"}},{"name":"project_id","in":"path","required":true,"description":"The UUID of the project","schema":{"type":"string","format":"uuid"}}],"description":"Generate key talking points for a specific section of the document.\n\nCreates structured bullet points that:\n- Highlight main ideas\n- Provide supporting details\n- Suggest examples or case studies\n- Identify potential questions to address\n\nUseful for presentations, summaries, or planning detailed content.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/compose/topic":{"post":{"tags":["Compose"],"summary":"Suggest Related Topics","operationId":"suggestTopics","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_compose"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComposeTopicPoint"},"examples":{"case_study_topic_brief":{"summary":"Topic Brief For The Case Study","value":{"title":"How Solstice Freight Cut Warehouse Putaway Time by 32%","category":"case_study"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Suggesttopics"}},"application/x-ndjson":{"schema":{"type":"string"},"examples":{"Topic Brief For The Case Study":{"summary":"Topic Brief For The Case Study","value":"{\"token\": \"A close look at how one regional freight operator\"}\n{\"token\": \" replaced ad-hoc warehouse habits with a repeatable\"}\n{\"token\": \" putaway workflow, and the operational metrics that\"}\n{\"token\": \" moved as a result. Written for operations leaders\"}\n{\"token\": \" who are weighing a workflow change against the\"}\n{\"token\": \" disruption of retraining pickers across multiple\"}\n{\"token\": \" sites during peak season.\"}"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Suggesttopics"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[{"name":"org_id","in":"path","required":true,"description":"The UUID of the organization","schema":{"type":"string","format":"uuid"}},{"name":"project_id","in":"path","required":true,"description":"The UUID of the project","schema":{"type":"string","format":"uuid"}}],"description":"Generate suggestions for related topics or content expansions.\n\nProvides intelligent recommendations for:\n- Related subjects to explore\n- Complementary sections to add\n- Cross-references to include\n- Follow-up documents to create\n\nHelps ensure comprehensive coverage of the subject matter.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/{entity_type}/tag":{"post":{"tags":["Tags"],"summary":"Create Tag","operationId":"createTag","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"entity_type","in":"path","required":true,"schema":{"enum":["task","task_revision","task_share","skill","task_agent_revision","task_agent_share"],"type":"string","examples":["task","task_agent_revision","task_agent_share"],"title":"Entity Type"},"description":"The type of entity this tag applies to (`task`, `task_revision`, `task_share`, `skill`, `task_agent_revision`, or `task_agent_share`)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagCreate"},"examples":{"environment_tag":{"summary":"Environment Tag","value":{"name":"production","description":"Production environment resources"}}}}}},"responses":{"200":{"description":"Tag created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"},"examples":{"Environment Tag":{"summary":"Environment Tag","value":{"id":"019f8a03-4d43-7001-8e4d-5d8f20713031","name":"production","description":"Tasks and revisions running in the live production environment","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","entity_type":"task","created_at":"2026-06-15T09:12:00Z","children":[],"is_project_tag":false,"is_global_tag":false,"tagged_entities":["019f8a06-6000-7002-8b1a-6e9031824052","019f8a06-6000-7003-8b1a-6e9031824053"]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid tag"}}},"description":"Bad Request - Invalid tag\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtag"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"409":{"description":"Conflict - Tag name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Tag name already exists"}}}},"500":{"description":"Internal Server Error - Failed to create tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a new tag for organizing resources.\n\nTags can be applied to supported entity types:\n- Tasks\n- Task revisions\n- Task shares\n- Skills\n- TaskAgent revisions\n- TaskAgent shares\n\nTags support hierarchical organization using prefixes."},"get":{"tags":["Tags"],"summary":"List Tags","operationId":"listTags","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"entity_type","in":"path","required":true,"schema":{"enum":["task","task_revision","task_share","skill","task_agent_revision","task_agent_share"],"type":"string","examples":["task","task_agent_revision","task_agent_share"],"title":"Entity Type"},"description":"The type of entity this tag applies to (`task`, `task_revision`, `task_share`, `skill`, `task_agent_revision`, or `task_agent_share`)."},{"name":"page_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"Tags retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_Tag_"},"examples":{"environment_tags":{"summary":"Environment Tags","value":{"results":[{"id":"019f8a03-4d43-7001-8e4d-5d8f20713031","name":"production","description":"Tasks and revisions running in the live production environment","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","entity_type":"task","created_at":"2026-06-15T09:12:00Z","children":[],"is_project_tag":false,"is_global_tag":false,"tagged_entities":["019f8a06-6000-7002-8b1a-6e9031824052","019f8a06-6000-7003-8b1a-6e9031824053"]},{"id":"019f8a03-4d43-7002-8e4d-5d8f20713032","name":"billing","description":"Tasks related to invoicing and billing workflows","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","entity_type":"task","created_at":"2026-06-20T14:05:00Z","children":[],"is_project_tag":false,"is_global_tag":false,"tagged_entities":["019f8a06-6000-7004-8b1a-6e9031824054"]}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid pagination"}}},"description":"Bad Request - Invalid pagination\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtags"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to list tags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List all tags in the project for the requested entity type."}},"/org/{org_id}/project/{project_id}/{entity_type}/tag/{tag_id}":{"post":{"tags":["Tags"],"summary":"Update Tag","operationId":"updateTag","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"entity_type","in":"path","required":true,"schema":{"enum":["task","task_revision","task_share","skill","task_agent_revision","task_agent_share"],"type":"string","examples":["task","task_agent_revision","task_agent_share"],"title":"Entity Type"},"description":"The type of entity this tag applies to (`task`, `task_revision`, `task_share`, `skill`, `task_agent_revision`, or `task_agent_share`)."},{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Tag Id"},"description":"The unique identifier (UUID) of the tag to operate on."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagUpdate"},"examples":{"update_name":{"summary":"Update Tag Name","value":{"name":"production-v2","description":"Updated production resources"}}}}}},"responses":{"200":{"description":"Tag updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"},"examples":{"Update Tag Name":{"summary":"Update Tag Name","value":{"id":"019f8a03-4d43-7001-8e4d-5d8f20713031","name":"production-v2","description":"Updated production resources","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","entity_type":"task","created_at":"2026-06-15T09:12:00Z","children":[],"is_project_tag":false,"is_global_tag":false,"tagged_entities":["019f8a06-6000-7002-8b1a-6e9031824052","019f8a06-6000-7003-8b1a-6e9031824053"]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid tag"}}},"description":"Bad Request - Invalid tag\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatetag"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"tags not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find tags [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"tags","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to update tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update tag properties"},"get":{"tags":["Tags"],"summary":"Get Tag","operationId":"getTag","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"entity_type","in":"path","required":true,"schema":{"enum":["task","task_revision","task_share","skill","task_agent_revision","task_agent_share"],"type":"string","examples":["task","task_agent_revision","task_agent_share"],"title":"Entity Type"},"description":"The type of entity this tag applies to (`task`, `task_revision`, `task_share`, `skill`, `task_agent_revision`, or `task_agent_share`)."},{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Tag Id"},"description":"The unique identifier (UUID) of the tag to operate on."}],"responses":{"200":{"description":"Tag details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"},"example":{"id":"019f8a03-4d43-7003-8e4d-5d8f20713033","name":"triage","description":"Inbound items awaiting review before routing","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","entity_type":"task","created_at":"2026-06-22T10:00:00Z","children":[{"id":"019f8a03-4d43-7004-8e4d-5d8f20713034","name":"urgent","description":"Highest-priority items awaiting triage","parent_id":"019f8a03-4d43-7003-8e4d-5d8f20713033","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","entity_type":"task","created_at":"2026-06-22T10:30:00Z","children":[],"is_project_tag":false,"is_global_tag":false,"tagged_entities":[]}],"is_project_tag":false,"is_global_tag":false,"tagged_entities":[]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettag"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"tags not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find tags [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"tags","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Get tag details for the requested entity type."}},"/org/{org_id}/project/{project_id}/{entity_type}/tag/{tag_id}/add":{"post":{"tags":["Tags"],"summary":"Add Tag to Entities","description":"Add a tag to multiple supported entities at once.","operationId":"addTagToEntities","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"entity_type","in":"path","required":true,"schema":{"enum":["task","task_revision","task_share","skill","task_agent_revision","task_agent_share"],"type":"string","examples":["task","task_agent_revision","task_agent_share"],"title":"Entity Type"},"description":"The type of entity this tag applies to (`task`, `task_revision`, `task_share`, `skill`, `task_agent_revision`, or `task_agent_share`)."},{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Tag Id"},"description":"The unique identifier (UUID) of the tag to operate on."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagEntityAdd"},"examples":{"two_tasks":{"summary":"Two tasks","value":{"entities":["019f8a06-6000-7002-8b1a-6e9031824052","019f8a06-6000-7003-8b1a-6e9031824053"]}}}}}},"responses":{"200":{"description":"Tag added to entities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"},"examples":{"Two tasks":{"summary":"Two tasks","value":{"id":"019f8a03-4d43-7001-8e4d-5d8f20713031","name":"production","description":"Tasks and revisions running in the live production environment","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","user_id":"019a2f10-9a4f-7e45-8e86-1c9d4e7b6f11","entity_type":"task","created_at":"2026-06-15T09:12:00.123456","parent_id":null,"is_project_tag":false,"is_global_tag":false,"children":[],"tagged_entities":["019f8a06-6000-7002-8b1a-6e9031824052","019f8a06-6000-7003-8b1a-6e9031824053"]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Addtagtoentities"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"One or more entity IDs were not found in the project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"type":"invalid_entity","loc":["body","entities"],"message":"Task with id 019a58ec-43b5-a1e5-60a8-c9653e6badbe not found in project 019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","input":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"tags not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find tags [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"tags","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to add tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/{entity_type}/tag/{tag_id}/remove":{"post":{"tags":["Tags"],"summary":"Remove Tag from Entities","description":"Remove a tag from multiple supported entities at once.","operationId":"removeTagFromEntities","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"entity_type","in":"path","required":true,"schema":{"enum":["task","task_revision","task_share","skill","task_agent_revision","task_agent_share"],"type":"string","examples":["task","task_agent_revision","task_agent_share"],"title":"Entity Type"},"description":"The type of entity this tag applies to (`task`, `task_revision`, `task_share`, `skill`, `task_agent_revision`, or `task_agent_share`)."},{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Tag Id"},"description":"The unique identifier (UUID) of the tag to operate on."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagEntityRemove"},"examples":{"two_tasks":{"summary":"Two tasks","value":{"entities":["019f8a06-6000-7002-8b1a-6e9031824052","019f8a06-6000-7003-8b1a-6e9031824053"]}}}}}},"responses":{"200":{"description":"Tag removed from entities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"},"examples":{"Two tasks":{"summary":"Two tasks","value":{"id":"019f8a03-4d43-7001-8e4d-5d8f20713031","name":"production","description":"Tasks and revisions running in the live production environment","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","user_id":"019a2f10-9a4f-7e45-8e86-1c9d4e7b6f11","entity_type":"task","created_at":"2026-06-15T09:12:00.123456","parent_id":null,"is_project_tag":false,"is_global_tag":false,"children":[],"tagged_entities":[]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Removetagfromentities"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"One or more entity IDs were not found in the project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"type":"invalid_entity","loc":["body","entities"],"message":"Task with id 019a58ec-43b5-a1e5-60a8-c9653e6badbe not found in project 019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","input":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"tags not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find tags [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"tags","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to remove tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/tags/{tag_id}":{"delete":{"tags":["Tags"],"summary":"Delete Tag","operationId":"deleteTag","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"tag_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Tag Id"},"description":"The unique identifier (UUID) of the tag to operate on."}],"responses":{"204":{"description":"Tag deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletetag"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"tags not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find tags [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"tags","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to delete tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Delete a tag and remove it from all resources"}},"/skills":{"get":{"tags":["Skills"],"summary":"List Skills","operationId":"listSkills","security":[{"HTTPBearer":[]}],"parameters":[{"name":"page_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"description":"Filter skills by source name."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"},"description":"Search skill slug, display name, and description."},{"name":"tag","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Tag"},"description":"Repeat to filter by one or more skill tags."},{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Tags"},"description":"Repeat to filter by one or more skill tags."}],"responses":{"200":{"description":"Successfully retrieved skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_SkillRead_"},"examples":{"catalog_page":{"summary":"First page of the catalog","description":"`next_cursor` is the id of the last entry on the page; pass it as `cursor` for the next one.","value":{"pagination":{"next_cursor":"019d6a02-3c30-7001-9d3c-4c7dbe602001","has_next":true,"page_limit":25},"results":[{"id":"019d6a01-2b20-7001-9c2b-3b6cad5f1001","slug":"internal-comms","display_name":"Internal Comms","description":"A set of resources to help write all kinds of internal communications, using the formats that a company likes to use. Use this skill when asked to write status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.","license":"Complete terms in LICENSE.txt","compatibility":null,"source":{"id":"019d6a00-1a10-7001-8b1a-2a5c9d4e0001","name":"anthropic","description":"Official Anthropic agent skills","url":"https://github.com/anthropics/skills"},"tags":[],"has_active_revision":true,"has_capabilities":false,"requires_prerequisites":false,"active_revision":{"id":"019d6a01-2b20-7002-9c2b-3b6cad5f1002","annotation":"Imported from anthropics/skills","created":"2026-03-25T14:47:34Z"},"created":"2026-03-25T14:47:34Z","modified":"2026-03-25T14:47:34Z"},{"id":"019d6a02-3c30-7001-9d3c-4c7dbe602001","slug":"brand-guidelines","display_name":"Brand Guidelines","description":"Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.","license":"Complete terms in LICENSE.txt","compatibility":null,"source":{"id":"019d6a00-1a10-7001-8b1a-2a5c9d4e0001","name":"anthropic","description":"Official Anthropic agent skills","url":"https://github.com/anthropics/skills"},"tags":[],"has_active_revision":true,"has_capabilities":false,"requires_prerequisites":false,"active_revision":{"id":"019d6a02-3c30-7002-9d3c-4c7dbe602002","annotation":"Imported from anthropics/skills","created":"2026-03-25T14:47:34Z"},"created":"2026-03-25T14:47:34Z","modified":"2026-03-25T14:47:34Z"}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Browse the global skill catalog using lightweight metadata only. Supports filtering by source, tag name, and free-text search."}},"/skills/sources":{"get":{"tags":["Skills"],"summary":"List Skill Sources","description":"List all available skill sources in the global catalog.","operationId":"listSkillSources","responses":{"200":{"description":"Skill sources","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SkillSourceRead"},"type":"array","title":"Response Listskillsources"},"examples":{"sources":{"summary":"Catalog sources","description":"Sources are returned as a bare array ordered by name. `url` is null for the `custom` source, which holds project-created skills.","value":[{"id":"019d6a00-1a10-7001-8b1a-2a5c9d4e0001","name":"anthropic","description":"Official Anthropic agent skills","url":"https://github.com/anthropics/skills"},{"id":"019d6a00-1a10-7003-8b1a-2a5c9d4e0003","name":"custom","description":"User-created skills","url":null},{"id":"019d6a00-1a10-7002-8b1a-2a5c9d4e0002","name":"rightbrain","description":"Rightbrain curated skills","url":"https://rightbrain.ai"}]}}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve skill sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"security":[{"HTTPBearer":[]}]}},"/skills/tags":{"get":{"tags":["Skills"],"summary":"List Skill Tags","operationId":"listSkillTags","security":[{"HTTPBearer":[]}],"parameters":[{"name":"page_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"Skill tags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_Tag_"},"examples":{"global_tags":{"summary":"Global skill tags","description":"Pass a `name` from these results as the `tag` query parameter on `GET /skills`. Global tags have no `project_id`.","value":{"pagination":{"next_cursor":"019d6a04-5e50-7002-9f5e-6e9fda824002","has_next":true,"page_limit":25},"results":[{"id":"019d6a04-5e50-7001-9f5e-6e9fda824001","name":"analysis","description":null,"parent_id":null,"project_id":null,"entity_type":"skill","created_at":"2026-03-19T08:49:44Z","children":[],"is_project_tag":true,"is_global_tag":true,"tagged_entities":[]},{"id":"019d6a04-5e50-7002-9f5e-6e9fda824002","name":"research","description":null,"parent_id":null,"project_id":null,"entity_type":"skill","created_at":"2026-03-19T08:49:44Z","children":[],"is_project_tag":true,"is_global_tag":true,"tagged_entities":[]}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve skill tags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List global skill tags available for filtering the declarative skill catalog."}},"/skills/{skill_id}/content":{"get":{"tags":["Skills"],"summary":"Get Skill Content","operationId":"getSkillContent","security":[{"HTTPBearer":[]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}}],"responses":{"200":{"description":"Skill content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillContentRead"},"examples":{"with_reference_files":{"summary":"Skill with reference files","description":"`reference_files` lists the filenames and `reference_file_contents` carries the same files with their bodies and sizes. File bodies are shortened here.","value":{"id":"019d6a01-2b20-7001-9c2b-3b6cad5f1001","slug":"internal-comms","display_name":"Internal Comms","description":"A set of resources to help write all kinds of internal communications, using the formats that a company likes to use. Use this skill when asked to write status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.","license":"Complete terms in LICENSE.txt","compatibility":null,"source":{"id":"019d6a00-1a10-7001-8b1a-2a5c9d4e0001","name":"anthropic","description":"Official Anthropic agent skills","url":"https://github.com/anthropics/skills"},"tags":[],"active_revision":{"id":"019d6a01-2b20-7002-9c2b-3b6cad5f1002","skill_id":"019d6a01-2b20-7001-9c2b-3b6cad5f1001","instructions":"## When to use this skill\nUse this skill for 3P updates, company newsletters, FAQ responses and\nleadership updates.\n\n## How to use this skill\n1. Identify the communication type from the request.\n2. Load the matching reference file.\n3. Draft the communication in that format.\n","skill_metadata":null,"capabilities":null,"annotation":"Imported from anthropics/skills","created":"2026-03-25T14:47:34Z","reference_files":["3p-updates","company-newsletter","faq-answers","general-comms"],"asset_files":[],"reference_file_contents":[{"path":"3p-updates","content":"Write a 3P update as three sections: Progress, Plans, Problems.\n","size_bytes":64,"size_kb":0.06},{"path":"company-newsletter","content":"Open with the single most important update, then three sections.\n","size_bytes":65,"size_kb":0.06},{"path":"faq-answers","content":"Answer in two sentences, then link the source of record.\n","size_bytes":57,"size_kb":0.06},{"path":"general-comms","content":"Lead with the decision, then the reason, then what changes.\n","size_bytes":60,"size_kb":0.06}],"asset_file_contents":[],"script_files":[]}}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve skill content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve the active revision content for a skill, including instructions, metadata, available reference or asset filenames, and structured file content entries with body size."}},"/skills/{skill_id}/revisions":{"get":{"tags":["Skills"],"summary":"List Skill Revisions","operationId":"listSkillRevisions","security":[{"HTTPBearer":[]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}}],"responses":{"200":{"description":"Skill revisions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SkillRevisionListItem"},"title":"Response Listskillrevisions"},"examples":{"single_revision":{"summary":"Skill imported once","description":"A catalog skill imported a single time has one revision. The response is a bare array, not a paginated envelope.","value":[{"id":"019d6a01-2b20-7002-9c2b-3b6cad5f1002","skill_id":"019d6a01-2b20-7001-9c2b-3b6cad5f1001","annotation":"Imported from anthropics/skills","created":"2026-03-25T14:47:34Z"}]}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve skill revisions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List all revisions for a skill from newest to oldest."}},"/skills/{skill_id}/revisions/{revision_id}":{"get":{"tags":["Skills"],"summary":"Get Skill Revision","operationId":"getSkillRevision","security":[{"HTTPBearer":[]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}},{"name":"revision_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Revision Id"}}],"responses":{"200":{"description":"Skill revision content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillRevisionContent"},"examples":{"instructions_only":{"summary":"Revision with no tool dependencies","description":"`skill_metadata` and `capabilities` are both null when the skill declares neither.","value":{"id":"019d6a01-2b20-7002-9c2b-3b6cad5f1002","skill_id":"019d6a01-2b20-7001-9c2b-3b6cad5f1001","instructions":"## When to use this skill\nUse this skill for 3P updates, company newsletters, FAQ responses and\nleadership updates.\n\n## How to use this skill\n1. Identify the communication type from the request.\n2. Load the matching reference file.\n3. Draft the communication in that format.\n","skill_metadata":null,"capabilities":null,"annotation":"Imported from anthropics/skills","created":"2026-03-25T14:47:34Z","reference_files":["3p-updates","company-newsletter","faq-answers","general-comms"],"asset_files":[],"reference_file_contents":[{"path":"3p-updates","content":"Write a 3P update as three sections: Progress, Plans, Problems.\n","size_bytes":64,"size_kb":0.06},{"path":"company-newsletter","content":"Open with the single most important update, then three sections.\n","size_bytes":65,"size_kb":0.06},{"path":"faq-answers","content":"Answer in two sentences, then link the source of record.\n","size_bytes":57,"size_kb":0.06},{"path":"general-comms","content":"Lead with the decision, then the reason, then what changes.\n","size_bytes":60,"size_kb":0.06}],"asset_file_contents":[],"script_files":[]}},"with_capabilities":{"summary":"Revision declaring tool dependencies","description":"`capabilities.dependencies` is what the catalog's `has_capabilities` and `requires_prerequisites` flags summarise.","value":{"id":"019d6a03-4d40-7002-9e4d-5d8ecf713002","skill_id":"019d6a03-4d40-7001-9e4d-5d8ecf713001","instructions":"## When to use this skill\nUse this skill to review pipeline health, forecast accuracy and\ngo-to-market efficiency.\n","skill_metadata":{"team":"revenue_operations","managed":true},"capabilities":{"schema_version":"1.0.0","dependencies":[{"id":"pipeline-analyzer","type":"registered_tool","required":true,"selector":{"kind":"registered_key","value":"pipeline-analyzer"}},{"id":"forecast-accuracy-tracker","type":"registered_tool","required":true,"selector":{"kind":"registered_key","value":"forecast-accuracy-tracker"}}]},"annotation":"Imported with a capability manifest","created":"2026-04-17T10:06:53Z","reference_files":["revops-metrics-guide.md"],"asset_files":["sample_pipeline_data.json"],"reference_file_contents":[{"path":"revops-metrics-guide.md","content":"# RevOps metrics\n\nDefinitions for pipeline coverage and win rate.\n","size_bytes":66,"size_kb":0.06}],"asset_file_contents":[{"path":"sample_pipeline_data.json","content":"{\"opportunities\": [{\"stage\": \"proposal\", \"value\": 42000}]}\n","size_bytes":59,"size_kb":0.06}],"script_files":[]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill revision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill_revision [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill_revision","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve skill revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve full content for a specific skill revision, including structured reference and asset file bodies with size metadata."}},"/skills/{skill_id}":{"get":{"tags":["Skills"],"summary":"Get Skill","operationId":"getSkill","security":[{"HTTPBearer":[]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}}],"responses":{"200":{"description":"Skill details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillRead"},"examples":{"imported_skill":{"summary":"Imported catalog skill","description":"`active_revision` summarises the revision the skill currently serves; use the content endpoint for its instructions and files.","value":{"id":"019d6a01-2b20-7001-9c2b-3b6cad5f1001","slug":"internal-comms","display_name":"Internal Comms","description":"A set of resources to help write all kinds of internal communications, using the formats that a company likes to use. Use this skill when asked to write status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.","license":"Complete terms in LICENSE.txt","compatibility":null,"source":{"id":"019d6a00-1a10-7001-8b1a-2a5c9d4e0001","name":"anthropic","description":"Official Anthropic agent skills","url":"https://github.com/anthropics/skills"},"tags":[],"has_active_revision":true,"has_capabilities":false,"requires_prerequisites":false,"active_revision":{"id":"019d6a01-2b20-7002-9c2b-3b6cad5f1002","annotation":"Imported from anthropics/skills","created":"2026-03-25T14:47:34Z"},"created":"2026-03-25T14:47:34Z","modified":"2026-03-25T14:47:34Z"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve lightweight metadata and active revision summary for a skill."}},"/org/{org_id}/project/{project_id}/skill":{"post":{"tags":["Skills"],"summary":"Create Project Skill","operationId":"createProjectSkill","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_skill"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillCreate"},"examples":{"basic":{"summary":"Skill with its initial revision","description":"`display_name` and `instructions` are the only required fields; the instructions become the first active revision.","value":{"display_name":"Refund Policy","description":"How to decide whether a refund request qualifies.","instructions":"Approve refunds requested within 30 days of purchase. Escalate anything older to finance."}}}}}},"responses":{"201":{"description":"Project skill created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillRead"},"examples":{"created":{"summary":"Skill with its initial revision","description":"`slug` is derived from `display_name`, the source is set to `custom`, and the initial revision is created and activated, so `has_active_revision` is already true.","value":{"id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","slug":"refund-policy","display_name":"Refund Policy","description":"How to decide whether a refund request qualifies.","license":null,"compatibility":null,"source":{"id":"019d6a00-1a10-7003-8b1a-2a5c9d4e0003","name":"custom","description":"User-created skills","url":null},"tags":[],"has_active_revision":true,"has_capabilities":false,"requires_prerequisites":false,"active_revision":{"id":"019d6b01-1a10-7002-8b1a-2a5c9d4e1002","annotation":"Initial revision","created":"2026-07-14T09:12:00Z"},"created":"2026-07-14T09:12:00Z","modified":"2026-07-14T09:12:00Z","project_id":"0190a234-9876-5432-10ab-cdef01234567","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createprojectskill"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_skill permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_skill"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid create project skill\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid create project skill","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"409":{"description":"Conflict - Skill already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Skill already exists"}}}},"500":{"description":"Internal Server Error - Failed to create project skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a project-scoped skill and its initial active revision in a single transaction."},"get":{"tags":["Skills"],"summary":"List Project Skills","operationId":"listProjectSkills","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"page_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"},"description":"Search skill slug, display name, and description."}],"responses":{"200":{"description":"Project skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_ProjectSkillRead_"},"examples":{"single_page":{"summary":"One skill, no further pages","description":"`next_cursor` is null on the last page. Only project-owned skills appear here; use the available endpoint to include the global catalog.","value":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":25},"results":[{"id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","slug":"refund-policy","display_name":"Refund Policy","description":"How to decide whether a refund request qualifies.","license":null,"compatibility":null,"source":{"id":"019d6a00-1a10-7003-8b1a-2a5c9d4e0003","name":"custom","description":"User-created skills","url":null},"tags":[],"has_active_revision":true,"has_capabilities":false,"requires_prerequisites":false,"active_revision":{"id":"019d6b01-1a10-7002-8b1a-2a5c9d4e1002","annotation":"Initial revision","created":"2026-07-14T09:12:00Z"},"created":"2026-07-14T09:12:00Z","modified":"2026-07-14T09:12:00Z","project_id":"0190a234-9876-5432-10ab-cdef01234567","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojectskills"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve project skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List project-owned skills visible within the current project."}},"/org/{org_id}/project/{project_id}/skill/available":{"get":{"tags":["Skills"],"summary":"List Available Skills","operationId":"listAvailableSkills","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"page_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Search"},"description":"Search skill slug, display name, and description."}],"responses":{"200":{"description":"Available skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_AvailableSkillRead_"},"examples":{"both_scopes":{"summary":"Project and global skills together","description":"`scope` distinguishes the two. Global entries have no `project_id` and no `created_by_user_id`; project-owned entries are returned first.","value":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":25},"results":[{"id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","slug":"refund-policy","display_name":"Refund Policy","description":"How to decide whether a refund request qualifies.","license":null,"compatibility":null,"source":{"id":"019d6a00-1a10-7003-8b1a-2a5c9d4e0003","name":"custom","description":"User-created skills","url":null},"tags":[],"has_active_revision":true,"has_capabilities":false,"requires_prerequisites":false,"active_revision":{"id":"019d6b01-1a10-7002-8b1a-2a5c9d4e1002","annotation":"Initial revision","created":"2026-07-14T09:12:00Z"},"created":"2026-07-14T09:12:00Z","modified":"2026-07-14T09:12:00Z","project_id":"0190a234-9876-5432-10ab-cdef01234567","created_by_user_id":"0190c234-1111-2222-3333-444444444444","scope":"project"},{"id":"019d6a01-2b20-7001-9c2b-3b6cad5f1001","slug":"internal-comms","display_name":"Internal Comms","description":"A set of resources to help write all kinds of internal communications, using the formats that a company likes to use. Use this skill when asked to write status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.","license":"Complete terms in LICENSE.txt","compatibility":null,"source":{"id":"019d6a00-1a10-7001-8b1a-2a5c9d4e0001","name":"anthropic","description":"Official Anthropic agent skills","url":"https://github.com/anthropics/skills"},"tags":[],"has_active_revision":true,"has_capabilities":false,"requires_prerequisites":false,"active_revision":{"id":"019d6a01-2b20-7002-9c2b-3b6cad5f1002","annotation":"Imported from anthropics/skills","created":"2026-03-25T14:47:34Z"},"created":"2026-03-25T14:47:34Z","modified":"2026-03-25T14:47:34Z","project_id":null,"created_by_user_id":null,"scope":"global"}]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listavailableskills"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve available skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List both global catalog skills and project-owned skills that can be attached to a TaskAgent in this project."}},"/org/{org_id}/project/{project_id}/skill/{skill_id}":{"get":{"tags":["Skills"],"summary":"Get Project Skill","operationId":"getProjectSkill","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"},"description":"The skill ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Project skill details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillRead"},"examples":{"project_skill":{"summary":"Project skill with its active revision","description":"`active_revision` is a summary only; use the content endpoint for its instructions.","value":{"id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","slug":"refund-policy","display_name":"Refund Policy","description":"How to decide whether a refund request qualifies.","license":null,"compatibility":null,"source":{"id":"019d6a00-1a10-7003-8b1a-2a5c9d4e0003","name":"custom","description":"User-created skills","url":null},"tags":[],"has_active_revision":true,"has_capabilities":false,"requires_prerequisites":false,"active_revision":{"id":"019d6b01-1a10-7002-8b1a-2a5c9d4e1002","annotation":"Initial revision","created":"2026-07-14T09:12:00Z"},"created":"2026-07-14T09:12:00Z","modified":"2026-07-14T09:12:00Z","project_id":"0190a234-9876-5432-10ab-cdef01234567","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojectskill"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve project skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve project-scoped skill metadata and active revision summary."},"post":{"tags":["Skills"],"summary":"Update Project Skill","operationId":"updateProjectSkill","security":[{"HTTPBearer":[]},{"HTTPBearer":["skill:edit"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"},"description":"The skill ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillUpdate"},"examples":{"rename":{"summary":"Update metadata only","description":"Metadata updates do not create a revision. Use the revision endpoint to change `instructions`.","value":{"display_name":"Refund Policy (EMEA)","description":"How to decide whether a refund request qualifies in EMEA."}}}}}},"responses":{"200":{"description":"Project skill updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillRead"},"examples":{"renamed":{"summary":"Update metadata only","description":"`modified` moves but `slug` does not: renaming the display name leaves the existing slug in place.","value":{"id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","slug":"refund-policy","display_name":"Refund Policy (EMEA)","description":"How to decide whether a refund request qualifies in EMEA.","license":null,"compatibility":null,"source":{"id":"019d6a00-1a10-7003-8b1a-2a5c9d4e0003","name":"custom","description":"User-created skills","url":null},"tags":[],"has_active_revision":true,"has_capabilities":false,"requires_prerequisites":false,"active_revision":{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","annotation":"Clarified the escalation path.","created":"2026-07-21T15:40:00Z"},"created":"2026-07-14T09:12:00Z","modified":"2026-07-21T15:40:00Z","project_id":"0190a234-9876-5432-10ab-cdef01234567","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateprojectskill"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"skill","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for Skill\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Skill belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid update project skill\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid update project skill","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"409":{"description":"Conflict - Skill already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Skill already exists"}}}},"500":{"description":"Internal Server Error - Failed to update project skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update project-scoped skill metadata."},"delete":{"tags":["Skills"],"summary":"Delete Project Skill","operationId":"deleteProjectSkill","security":[{"HTTPBearer":[]},{"HTTPBearer":["skill:edit"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"},"description":"The skill ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"204":{"description":"Project skill deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deleteprojectskill"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"skill","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for Skill\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Skill belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to delete project skill","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Soft-delete a project-scoped skill."}},"/org/{org_id}/project/{project_id}/skill/{skill_id}/content":{"get":{"tags":["Skills"],"summary":"Get Project Skill Content","operationId":"getProjectSkillContent","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"},"description":"The skill ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Project skill content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillContentRead"},"examples":{"instructions_only":{"summary":"Skill created from instructions alone","description":"A skill created without files has empty file lists and a null `skill_metadata` and `capabilities`. This response carries no `project_id`; use the skill endpoint for that.","value":{"id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","slug":"refund-policy","display_name":"Refund Policy","description":"How to decide whether a refund request qualifies.","license":null,"compatibility":null,"source":{"id":"019d6a00-1a10-7003-8b1a-2a5c9d4e0003","name":"custom","description":"User-created skills","url":null},"tags":[],"active_revision":{"id":"019d6b01-1a10-7002-8b1a-2a5c9d4e1002","skill_id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","instructions":"Approve refunds requested within 30 days of purchase. Escalate anything older to finance.","skill_metadata":null,"capabilities":null,"annotation":"Initial revision","created":"2026-07-14T09:12:00Z","reference_files":[],"asset_files":[],"reference_file_contents":[],"asset_file_contents":[],"script_files":[]}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojectskillcontent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve project skill content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve the active revision content for a project-scoped skill."}},"/org/{org_id}/project/{project_id}/skill/{skill_id}/revision":{"post":{"tags":["Skills"],"summary":"Create Project Skill Revision","operationId":"createProjectSkillRevision","security":[{"HTTPBearer":[]},{"HTTPBearer":["skill:edit"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"},"description":"The skill ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillRevisionCreate"},"examples":{"draft":{"summary":"New revision, left inactive","description":"`activate` defaults to false, so the revision is created without changing what the skill serves.","value":{"instructions":"Approve refunds requested within 30 days. Escalate older requests to finance.","annotation":"Clarified the escalation path.","activate":false}}}}}},"responses":{"201":{"description":"Project skill revision created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillRevisionContent"},"examples":{"created":{"summary":"New revision, left inactive","description":"The full revision content is returned. Nothing in the response records whether the revision is active — read the skill to see which revision it now serves.","value":{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","skill_id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","instructions":"Approve refunds requested within 30 days. Escalate older requests to finance.","skill_metadata":null,"capabilities":null,"annotation":"Clarified the escalation path.","created":"2026-07-21T15:40:00Z","reference_files":[],"asset_files":[],"reference_file_contents":[],"asset_file_contents":[],"script_files":[]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createprojectskillrevision"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"skill","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for Skill\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Skill belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid create project skill revision\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid create project skill revision","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to create project skill revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a new revision for a project-scoped skill."},"get":{"tags":["Skills"],"summary":"List Project Skill Revisions","operationId":"listProjectSkillRevisions","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"},"description":"The skill ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Project skill revisions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SkillRevisionListItem"},"title":"Response Listprojectskillrevisions"},"examples":{"two_revisions":{"summary":"Initial revision plus one edit","description":"A bare array, newest first. Summaries only — no instructions and no active flag.","value":[{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","skill_id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","annotation":"Clarified the escalation path.","created":"2026-07-21T15:40:00Z"},{"id":"019d6b01-1a10-7002-8b1a-2a5c9d4e1002","skill_id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","annotation":"Initial revision","created":"2026-07-14T09:12:00Z"}]}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojectskillrevisions"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve project skill revisions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List all revisions for a project-scoped skill from newest to oldest."}},"/org/{org_id}/project/{project_id}/skill/{skill_id}/revision/{revision_id}":{"get":{"tags":["Skills"],"summary":"Get Project Skill Revision","operationId":"getProjectSkillRevision","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"},"description":"The skill ID"},{"name":"revision_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Revision Id"},"description":"The skill revision ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Project skill revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectSkillRevisionContent"},"examples":{"revision":{"summary":"A revision's full content","description":"Identical in shape to the create-revision response.","value":{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","skill_id":"019d6b01-1a10-7001-8b1a-2a5c9d4e1001","instructions":"Approve refunds requested within 30 days. Escalate older requests to finance.","skill_metadata":null,"capabilities":null,"annotation":"Clarified the escalation path.","created":"2026-07-21T15:40:00Z","reference_files":[],"asset_files":[],"reference_file_contents":[],"asset_file_contents":[],"script_files":[]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojectskillrevision"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill revision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill_revision [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill_revision","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve project skill revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve full content for a specific project-scoped skill revision."}},"/org/{org_id}/project/{project_id}/skill/{skill_id}/activate":{"post":{"tags":["Skills"],"summary":"Activate Project Skill Revision","operationId":"activateProjectSkillRevision","security":[{"HTTPBearer":[]},{"HTTPBearer":["skill:edit"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"},"description":"The skill ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillActivateRevisionRequest"},"examples":{"activate":{"summary":"Activate a revision","value":{"revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4"}}}}}},"responses":{"200":{"description":"Project skill revision activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillRevisionSummary"},"examples":{"activated":{"summary":"Activate a revision","description":"Only the summary of the now-active revision is returned, not the whole skill.","value":{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","annotation":"Clarified the escalation path.","created":"2026-07-21T15:40:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Activateprojectskillrevision"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on skill [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"skill","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for Skill\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Skill belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid activate project skill revision\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid activate project skill revision","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Skill revision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find skill_revision [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"skill_revision","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to activate project skill revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Set a specific revision as the active revision for a project skill."}},"/org/{org_id}/project/{project_id}/skill/{skill_id}/iam/members":{"get":{"tags":["Skills"],"summary":"IAM - List Skill Members","description":"Lists all members that have been granted direct access to the skill.","operationId":"skill_iam_org_org_id_project_project_id_skill_skill_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["skill:view","skill:view_members"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Skill members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Skill Iam Org Org Id Project Project Id Skill Skill Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/skill/{skill_id}/iam/members/{member}":{"get":{"tags":["Skills"],"summary":"IAM - Lookup Skill Member","description":"Retrieve a specific member that has been granted direct access to the skill.","operationId":"skill_iam_org_org_id_project_project_id_skill_skill_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["skill:view","skill:view_members"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Skill member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Skill Iam Org Org Id Project Project Id Skill Skill Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Skills"],"summary":"IAM - Update Skill Member","description":"Update the roles that a member holds on the skill.","operationId":"skill_iam_org_org_id_project_project_id_skill_skill_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["skill:view"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Skill member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Skill Iam Org Org Id Project Project Id Skill Skill Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Skill Iam Org Org Id Project Project Id Skill Skill Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/skill/{skill_id}/iam/test":{"post":{"tags":["Skills"],"summary":"IAM - Test Skill Permissions","description":"Test the permissions that the caller (or another subject) holds on the skill.","operationId":"skill_iam_org_org_id_project_project_id_skill_skill_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["skill:view"]}],"parameters":[{"name":"skill_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Skill Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Skill permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Skill Iam Org Org Id Project Project Id Skill Skill Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Skill Iam Org Org Id Project Project Id Skill Skill Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/reporting-groups":{"post":{"tags":["Reporting Groups"],"summary":"Create Reporting Group","description":"Create a new reporting group within a project.\n\nReporting groups help organize and segment task usage for analytics and billing purposes.\nEach project can have multiple reporting groups based on the organization's plan:\n- Trial/Pro plans: Up to 10 reporting groups\n- Teams plan: Up to 20 reporting groups\n- Enterprise plan: Up to 50 reporting groups\n\nThe reporting group name must be unique within the project.","operationId":"createReportingGroup","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingGroupCreate"},"examples":{"basic":{"summary":"Basic reporting group","value":{"name":"engineering-team","description":"Tasks run by the engineering department"}}}}}},"responses":{"201":{"description":"Reporting group created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingGroup"},"examples":{"Basic reporting group":{"summary":"Basic reporting group","value":{"id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","name":"engineering-team","description":"Tasks run by the engineering department","project_id":"0190a234-5678-1234-abcd-123456789012","created":"2026-01-15T10:30:00Z","modified":"2026-01-15T10:30:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createreportinggroup"}}},"description":"Forbidden"},"422":{"description":"Invalid request or plan limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"duplicate_name":{"summary":"Duplicate name","value":{"detail":[{"type":"duplicate_reporting_group_name","loc":["body","name"],"msg":"Reporting group name already exists in this project","input":"engineering-team"}]}},"limit_exceeded":{"summary":"Plan limit exceeded","value":{"detail":[{"type":"reporting_group_limit_exceeded","loc":["body"],"msg":"Cannot create reporting group. Plan 'pro' allows a maximum of 10 reporting groups. Current count: 10","input":{"name":"engineering-team"}}]}}}}}},"500":{"description":"Internal Server Error - Failed to create reporting group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"get":{"tags":["Reporting Groups"],"summary":"List Reporting Groups","description":"List all reporting groups within a project.\n\nReturns a paginated list of reporting groups ordered by creation date (newest first).\nUse the cursor and page_limit parameters to navigate through large result sets.","operationId":"listReportingGroups","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"Pagination cursor for the next page of results."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"Maximum number of reporting groups to return per page."}],"responses":{"200":{"description":"Successfully retrieved reporting groups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_ReportingGroup_"},"example":{"results":[{"id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","name":"engineering-team","description":"Tasks run by the engineering department","project_id":"0190a234-5678-1234-abcd-123456789012","created":"2026-01-15T10:30:00Z","modified":"2026-01-15T10:30:00Z"},{"id":"0190a234-9abc-2345-bcde-234567890123","name":"Customer Success","description":"Support and customer success operations","project_id":"0190a234-5678-1234-abcd-123456789012","created":"2024-01-14T09:15:00Z","modified":"2024-01-14T09:15:00Z"}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listreportinggroups"}}},"description":"Forbidden"},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"500":{"description":"Internal Server Error - Failed to list reporting groups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/reporting-groups/{reporting_group_id}":{"get":{"tags":["Reporting Groups"],"summary":"Get Reporting Group","description":"Retrieve details of a specific reporting group.\n\nReturns the complete reporting group information.","operationId":"getReportingGroup","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"reporting_group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Reporting Group Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Reporting group details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingGroup"},"example":{"id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","name":"engineering-team","description":"Tasks run by the engineering department","project_id":"0190a234-5678-1234-abcd-123456789012","created":"2026-01-15T10:30:00Z","modified":"2026-01-16T14:20:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getreportinggroup"}}},"description":"Forbidden"},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"404":{"description":"Reporting group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Reporting group not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve reporting group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"post":{"tags":["Reporting Groups"],"summary":"Update Reporting Group","description":"Update an existing reporting group's properties.\n\nAllows updating the name and description of a reporting group.\nThe name must remain unique within the project.","operationId":"updateReportingGroup","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"reporting_group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Reporting Group Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingGroupUpdate"},"examples":{"update_name":{"summary":"Update name and description","value":{"name":"engineering-backend","description":"Backend engineering team tasks"}}}}}},"responses":{"200":{"description":"Reporting group updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingGroup"},"examples":{"Update name and description":{"summary":"Update name and description","value":{"id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","name":"engineering-backend","description":"Backend engineering team tasks","project_id":"0190a234-5678-1234-abcd-123456789012","created":"2026-01-15T10:30:00Z","modified":"2026-01-20T16:45:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatereportinggroup"}}},"description":"Forbidden"},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"404":{"description":"Reporting group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Reporting group not found"}}}},"409":{"description":"Conflict - Reporting group already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Reporting group with name 'engineering-team' already exists in this project"}}}},"500":{"description":"Internal Server Error - Failed to update reporting group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"delete":{"tags":["Reporting Groups"],"summary":"Delete Reporting Group","description":"Delete a reporting group from the project.\n\nThis operation permanently removes the reporting group. Any tasks associated with\nthis reporting group will no longer be segmented by this grouping. Historical\nanalytics data may be retained but will no longer be associated with this group.","operationId":"deleteReportingGroup","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"reporting_group_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Reporting Group Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"204":{"description":"Reporting group deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletereportinggroup"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Reporting group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Reporting group not found"}}}},"500":{"description":"Internal Server Error - Failed to delete reporting group","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task":{"post":{"tags":["Tasks"],"summary":"Create a New Task","description":"Create a new Task with specified prompts, model configuration, and output format.\n\nTasks are the core building blocks that define how the LLM processes inputs and generates structured outputs. Each Task includes:\n- System and user prompts that guide the LLM's behavior\n- Input parameters that can be dynamically provided when running the Task\n- Output format specification that ensures consistent, structured responses\n- Output modality supporting multiple formats:\n  - `json`: Structured JSON responses (default)\n  - `image`: AI-generated images (requires image-capable model)\n  - `audio`: Voice/audio responses\n  - `pdf`: Formatted PDF documents\n  - `text`: Plain text output\n  - `csv`: Structured CSV data tables\n- Optional fallback model for improved reliability when primary model fails\n- Optional task run visibility controls for managing access to task execution history\n- Optional image processing capabilities\n- Optional RAG (Retrieval Augmented Generation) for domain-specific knowledge\n\nUse `integration_bindings` to attach Integration tools and choose runtime\ncredentials. Clients can author `project_default` for the project's shared\nconnection or `invoker` for the eligible invoking user's connection. Migrated\n`fixed_connection` bindings are read-only and can only be preserved on revision\nupdates through their source `binding_id`. `integration_tool_ids` is deprecated.\n\n**LLM Configuration (`llm_config`):**\nModel-specific configuration options. Common parameters include:\n- `temperature` (0.0-2.0): Controls randomness. Lower = more focused, higher = more creative\n- `top_p` (0.0-1.0): Nucleus sampling. Use either temperature OR top_p, not both\n- `max_tokens`: Maximum tokens in the response\n- `quality` (for image models): \"standard\" or \"hd\"\n- `size` (for image models): e.g., \"1024x1024\", \"1792x1024\"\n\n**Output Format (`output_format`):**\nDefine the structure of task outputs. Two syntaxes are supported:\n\n*Shorthand syntax* (simple fields):\n```json\n{\"field_name\": \"str\", \"count\": \"int\", \"items\": \"array\"}\n```\n\n*Object syntax* (with descriptions and constraints):\n```json\n{\n  \"field_name\": {\n    \"type\": \"str\",\n    \"description\": \"What this field contains\",\n    \"options\": [\"option1\", \"option2\"]\n  }\n}\n```\n\nSupported types: `str`/`string`, `int`/`integer`, `number`, `bool`/`boolean`, `list`, `object`\n\n`output_format` is **required** when `output_modality` is `json` (the default), and must be omitted when `output_modality` is `image`, `text`, or `csv`.\n\n**Task Run Visibility:**\n- `owner_only` (default): Only task owners can view all task runs\n- `editors_and_owners`: Task editors and owners can view all task runs\n- `all_viewers`: All users with view permission can see all task runs\n\n**File Input Mode (`file_input_mode`):**\nSpecifies what file types are accepted for visual LLM processing:\n- `none` (default): No file input accepted\n- `image`: Image file required (PNG, JPEG, WebP, GIF)\n- `pdf`: PDF document required (requires PDF vision model)\n- `image_or_pdf`: Either image or PDF accepted\n- `any`: Any visually processable file accepted\n\n**PDF Vision Model Compatibility:**\n- Gemini 1.5/2.x/3.x models: Up to 50MB, 1000 pages\n- Claude 3.x/4.x models: Up to 30MB, 100 pages visual\n- GPT-4o models: Up to 20MB\n- GPT-3.5 / Groq: No PDF vision support\n\n**Common Use Cases:**\n\n*Structured Data Extraction:*\nCreate tasks with JSON output to extract structured data from unstructured text (e.g., invoice parsing, contact extraction).\n\n*Image Generation:*\nSet `output_modality: \"image\"` with DALL-E or similar models to generate images from text prompts.\n\n*Document Analysis with Vision:*\nSet `file_input_mode` to accept images, PDFs, or both for visual analysis by the LLM. Use PDF-capable models (Gemini, Claude, GPT-4o) for direct PDF processing without text extraction.\n\n*Knowledge Base Q&A (RAG):*\nConfigure `rag` with collection IDs to ground responses in your organization's documents and knowledge.\n\n*Automated Reports:*\nUse `output_modality: \"pdf\"` to generate formatted reports that can be downloaded or emailed.\n\n**Template resource identifiers:**\nThe request examples below are templates, not universally executable payloads.\nReplace every `llm_model_id` and `fallback_llm_model_id` with an available model\nID returned by `getAllModels` for the target project. For the RAG example, also\nreplace `rag.collection_id` with a collection ID returned by `listCollections`\nin that project. The fixed UUIDs only show where those project-scoped resource\nIDs belong.\n\nThe Task will be created with an initial revision that becomes automatically active.","operationId":"createTask","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_task"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCreate"},"examples":{"support_ticket_triage":{"summary":"Support ticket triage","description":"Classify inbound support tickets and draft a summary for the on-call agent","value":{"name":"Support Ticket Triage","description":"Classifies inbound support tickets by category and priority, and drafts a one-line summary for the on-call agent.","system_prompt":"You are a support triage assistant for a B2B SaaS helpdesk. Read each ticket and classify it accurately so it reaches the right team quickly.","user_prompt":"Ticket subject: {subject}\n\nTicket body: {body}\n\nCustomer plan: {plan}","output_format":{"category":{"type":"str","description":"The team best suited to handle this ticket","options":["account","billing","feature_request","technical"]},"priority":{"type":"str","description":"How urgently the ticket needs a response","options":["high","low","medium","urgent"]},"summary":{"type":"str","description":"One-sentence summary of the customer's issue"}},"llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","enabled":true,"exposed_to_agents":true,"public":false,"output_modality":"json","task_run_visibility":"editors_and_owners","annotation":"Initial production revision"}},"with_integration":{"summary":"Task with a project connection","value":{"name":"Spreadsheet Lookup","system_prompt":"Use the attached spreadsheet tool.","user_prompt":"Look up: {query}","output_format":{"answer":"str"},"llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","enabled":true,"tool_choice":"auto","integration_bindings":[{"project_integration_id":"019f8a04-5e54-7004-9f5e-6e9031824044","integration_tool_ids":["019f8a04-5e54-7005-9f5e-6e9031824045"],"credential_policy":"project_default"}]}},"output_modalities":{"summary":"Non-JSON output modalities (image/audio/pdf/text/csv)","description":"Change output_modality to: image, audio, pdf, text, or csv","value":{"name":"Logo Generator","description":"Generates logos based on description","system_prompt":"You are an AI that generates logo descriptions for image generation.","user_prompt":"Create a logo for: {company_description}","llm_model_id":"c3847a5f-8b2e-4f8a-b1c9-d238e4a5f3b2","llm_config":{"quality":"standard","size":"1024x1024"},"output_modality":"image","enabled":true}},"with_rag":{"summary":"Task with RAG enabled","value":{"name":"Knowledge QA","description":"Answers questions using knowledge base","system_prompt":"You are a helpful assistant. Use the provided context to answer questions.","user_prompt":"Context: {context}\n\nQuestion: {question}","output_format":{"answer":{"type":"str","description":"Answer to the question"},"confidence":{"type":"number","description":"Confidence score"}},"llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","rag":{"collection_id":"01908843-1234-5678-9abc-def012345678","rag_config":{"rewrite_mode":"single_query","final_k":5}},"enabled":true,"exposed_to_agents":true,"output_modality":"json"}},"image_processing":{"summary":"Task with image support","value":{"name":"Image Analyzer","description":"Analyzes and describes images","system_prompt":"You are an image analysis expert.","user_prompt":"Analyze this image and describe: {description_type}","output_format":{"description":{"type":"str","description":"Image description"},"objects":{"type":"list","item_type":"str","description":"Detected objects"}},"llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","file_input_mode":"image","optimise_images":true,"enabled":true}},"with_input_processors":{"summary":"Task with input processors","value":{"name":"URL Content Analyzer","description":"Analyzes content from URLs","system_prompt":"You are a content analyzer.","user_prompt":"Analyze this content: {url}","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","input_processors":[{"param_name":"url","input_processor":"url_fetcher","config":{"timeout":30}}],"output_format":{"summary":"str","sentiment":{"type":"str","options":["negative","neutral","positive"]}},"enabled":true,"exposed_to_agents":true,"annotation":"Testing URL content analysis with input processors"}},"advanced_reliability":{"summary":"Fallback model + visibility settings","description":"Combines fallback model for reliability with visibility controls","value":{"name":"Reliable Team Task","description":"Task with fallback model and collaborative visibility","system_prompt":"You are a helpful assistant.","user_prompt":"Process: {input}","output_format":{"result":{"type":"str","description":"Processed result"}},"llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_config":{"temperature":0.5},"enabled":true,"task_run_visibility":"editors_and_owners","public":false}}}}}},"responses":{"200":{"description":"Task created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"},"examples":{"Support ticket triage":{"summary":"Support ticket triage","value":{"id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","name":"Support Ticket Triage","description":"Classifies inbound support tickets by category and priority, and drafts a one-line summary for the on-call agent.","enabled":true,"public":false,"exposed_to_agents":true,"output_modality":"json","task_run_visibility":"editors_and_owners","created":"2026-07-20T09:14:32Z","modified":"2026-07-20T09:14:32Z","access_token":"TASK_ACCESS_TOKEN_REDACTED","active_revisions":[{"task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","weight":1.0}],"revisions":[{"id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","system_prompt":"You are a support triage assistant for a B2B SaaS helpdesk. Read each ticket and classify it accurately so it reaches the right team quickly.","user_prompt":"Ticket subject: {subject}\n\nTicket body: {body}\n\nCustomer plan: {plan}","llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","llm_config":{"temperature":0.2},"output_format":{"category":{"type":"str","description":"The team best suited to handle this ticket","options":["account","billing","feature_request","technical"]},"priority":{"type":"str","description":"How urgently the ticket needs a response","options":["high","low","medium","urgent"]},"summary":{"type":"str","description":"One-sentence summary of the customer's issue"}},"file_input_mode":"none","optimise_images":true,"test":false,"input_processors":[],"annotation":"Initial production revision","task_mcp_tool_ids":[],"integration_tool_ids":[],"integration_bindings":[],"active":true,"created":"2026-07-20T09:14:32Z","modified":"2026-07-20T09:14:32Z","tags":[],"input_params":["subject","body","plan"],"llm_model":{"id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","provider":"Anthropic","vendor":"anthropic","name":"claude-sonnet-5","alias":"Claude Sonnet 5","description":"Balanced reasoning and speed for structured classification and extraction tasks.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":true,"max_context_window":200000,"model_params":{"temperature":{"type":"number","default":0.3,"maximum":1.0,"minimum":0.0,"description":"Controls randomness in the output. Lower values make output more focused and deterministic."}},"created":"2026-01-05T00:00:00Z","modified":"2026-01-05T00:00:00Z","llm_model_comments":[]}}],"tags":[],"shared_with_project":false}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid task configuration"}}},"description":"Bad Request - Invalid task configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtask"},"examples":{"project_create_task":{"summary":"Missing create_task on project","value":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_task permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_task"}}}}}}},"description":"Forbidden - insufficient permission for this operation"},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to create task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"get":{"tags":["Tasks"],"summary":"List Tasks","operationId":"listTasks","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":"Filter tasks by name (case-insensitive partial match)."},{"name":"tag_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tag Id"},"description":"Filter tasks by tag ID."},{"name":"created_by_me","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Created By Me"},"description":"Filter tasks to those created by the current user."},{"name":"include_tests","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Include Tests"},"description":"Include test revisions"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"Pagination cursor for the next page of results."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"Maximum number of tasks to return per page."}],"responses":{"200":{"description":"Successfully retrieved paginated tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_Task_"},"example":{"results":[{"id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","name":"Support Ticket Triage","description":"Classifies inbound support tickets by category and priority, and drafts a one-line summary for the on-call agent.","enabled":true,"public":false,"exposed_to_agents":true,"output_modality":"json","task_run_visibility":"editors_and_owners","created":"2026-07-20T09:14:32Z","modified":"2026-07-25T16:20:05Z","access_token":"TASK_ACCESS_TOKEN_REDACTED","active_revisions":[{"task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","weight":1.0}],"revisions":[{"id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","system_prompt":"You are a support triage assistant for a B2B SaaS helpdesk. Read each ticket and classify it accurately so it reaches the right team quickly.","user_prompt":"Ticket subject: {subject}\n\nTicket body: {body}\n\nCustomer plan: {plan}","llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","llm_config":{"temperature":0.2},"output_format":{"category":{"type":"str","description":"The team best suited to handle this ticket","options":["account","billing","feature_request","technical"]},"priority":{"type":"str","description":"How urgently the ticket needs a response","options":["high","low","medium","urgent"]},"summary":{"type":"str","description":"One-sentence summary of the customer's issue"}},"file_input_mode":"none","optimise_images":true,"test":false,"input_processors":[],"annotation":"Initial production revision","task_mcp_tool_ids":[],"integration_tool_ids":[],"integration_bindings":[],"active":true,"created":"2026-07-20T09:14:32Z","modified":"2026-07-20T09:14:32Z","tags":[],"input_params":["subject","body","plan"],"llm_model":{"id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","provider":"Anthropic","vendor":"anthropic","name":"claude-sonnet-5","alias":"Claude Sonnet 5","description":"Balanced reasoning and speed for structured classification and extraction tasks.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":true,"max_context_window":200000,"model_params":{"temperature":{"type":"number","default":0.3,"maximum":1.0,"minimum":0.0,"description":"Controls randomness in the output. Lower values make output more focused and deterministic."}},"created":"2026-01-05T00:00:00Z","modified":"2026-01-05T00:00:00Z","llm_model_comments":[]}},{"id":"019f8a06-aa82-7da7-b159-8bb1d36bab06","system_prompt":"You are a support triage assistant for a B2B SaaS helpdesk. Classify each ticket, flag churn risk, and route it to the right team quickly.","user_prompt":"Ticket subject: {subject}\n\nTicket body: {body}\n\nCustomer plan: {plan}","llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","llm_config":{"temperature":0.2},"output_format":{"category":{"type":"str","description":"The team best suited to handle this ticket","options":["account","billing","feature_request","technical"]},"priority":{"type":"str","description":"How urgently the ticket needs a response","options":["high","low","medium","urgent"]},"summary":{"type":"str","description":"One-sentence summary of the customer's issue"},"churn_risk":{"type":"bool","description":"True if the customer shows signs of churn risk"}},"file_input_mode":"none","optimise_images":true,"test":false,"input_processors":[],"annotation":"Added churn-risk signal to prioritization","task_mcp_tool_ids":[],"integration_tool_ids":[],"integration_bindings":[],"active":false,"created":"2026-07-25T16:20:00Z","modified":"2026-07-25T16:20:00Z","tags":[],"input_params":["subject","body","plan"],"llm_model":{"id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","provider":"Anthropic","vendor":"anthropic","name":"claude-sonnet-5","alias":"Claude Sonnet 5","description":"Balanced reasoning and speed for structured classification and extraction tasks.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":true,"max_context_window":200000,"model_params":{"temperature":{"type":"number","default":0.3,"maximum":1.0,"minimum":0.0,"description":"Controls randomness in the output. Lower values make output more focused and deterministic."}},"created":"2026-01-05T00:00:00Z","modified":"2026-01-05T00:00:00Z","llm_model_comments":[]}}],"tags":[],"shared_with_project":false},{"id":"019f8a02-6c4e-7f63-8d15-4c7e9f2b6d82","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","name":"Invoice Line-Item Extractor","description":"Extracts vendor, line items, and totals from uploaded invoice PDFs for AP automation.","enabled":true,"public":false,"exposed_to_agents":false,"output_modality":"json","task_run_visibility":"owner_only","created":"2026-06-02T08:00:00Z","modified":"2026-06-02T08:00:00Z","access_token":"TASK_ACCESS_TOKEN_REDACTED","active_revisions":[{"task_revision_id":"019f8a03-7d5f-7a74-9e26-5d8fa03c7e93","weight":1.0}],"revisions":[{"id":"019f8a03-7d5f-7a74-9e26-5d8fa03c7e93","system_prompt":"You are an accounts-payable assistant that extracts structured data from invoices. Only report values you can read directly from the document.","user_prompt":"Extract the vendor name, invoice number, due date, and line items from this invoice.","llm_model_id":"019f6a03-2b6f-7f75-ac4e-8d9fab2c3f24","llm_config":{"temperature":0.0},"output_format":{"vendor_name":{"type":"str","description":"Name of the vendor issuing the invoice"},"invoice_number":{"type":"str","description":"Invoice number or reference"},"due_date":{"type":"str","description":"Payment due date, ISO 8601 if present"},"total_amount":{"type":"number","description":"Total amount due"},"line_items":{"type":"list","item_type":"object","description":"Individual line items on the invoice","nested_structure":{"description":"str","quantity":"number","unit_price":"number","amount":"number"}}},"file_input_mode":"pdf","optimise_images":true,"test":false,"input_processors":[],"annotation":"Initial production revision","task_mcp_tool_ids":[],"integration_tool_ids":[],"integration_bindings":[],"active":true,"created":"2026-06-02T08:00:00Z","modified":"2026-06-02T08:00:00Z","tags":[],"llm_model":{"id":"019f6a03-2b6f-7f75-ac4e-8d9fab2c3f24","provider":"OpenAI","vendor":"openai","name":"gpt-4.1","alias":"GPT-4.1","description":"Multimodal model with strong document understanding, used here for direct PDF invoice extraction.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":true,"supports_tool_calling":true,"supports_context_caching":false,"pdf_vision_config":{"max_file_size_mb":20},"max_context_window":1000000,"model_params":{},"created":"2026-02-01T00:00:00Z","modified":"2026-02-01T00:00:00Z","llm_model_comments":[]},"input_params":[]}],"tags":[],"shared_with_project":true}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid pagination parameters"}}},"description":"Bad Request - Invalid pagination parameters\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtasks"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list tasks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List all Tasks in the project with pagination support.\n\nReturns a paginated list of Tasks with their basic information:\n- Task ID and metadata\n- Active revision status\n- Latest modification time\n- Tags\n\nUse the page_limit and cursor parameters to navigate through the results."}},"/org/{org_id}/project/{project_id}/task/{task_id}":{"post":{"tags":["Tasks"],"summary":"Update a Task","operationId":"updateTask","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskUpdate"},"examples":{"basic_update":{"summary":"Update task metadata","value":{"name":"Updated Task Name","description":"Updated description"}},"new_revision":{"summary":"Create new revision","description":"Add a churn-risk signal to the Support Ticket Triage output without activating it yet","value":{"system_prompt":"You are a support triage assistant for a B2B SaaS helpdesk. Classify each ticket, flag churn risk, and route it to the right team quickly.","user_prompt":"Ticket subject: {subject}\n\nTicket body: {body}\n\nCustomer plan: {plan}","output_format":{"category":{"type":"str","description":"The team best suited to handle this ticket","options":["account","billing","feature_request","technical"]},"priority":{"type":"str","description":"How urgently the ticket needs a response","options":["high","low","medium","urgent"]},"summary":{"type":"str","description":"One-sentence summary of the customer's issue"},"churn_risk":{"type":"bool","description":"True if the customer shows signs of churn risk"}},"llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","annotation":"Added churn-risk signal to prioritization","test":false}},"update_visibility":{"summary":"Update task visibility","value":{"exposed_to_agents":true,"enabled":true,"task_run_visibility":"all_viewers"}},"test_revision":{"summary":"Create test revision","value":{"system_prompt":"Test prompt","user_prompt":"Test: {input}","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","test":true,"annotation":"Testing new approach","optimise_images":false}},"with_fallback":{"summary":"Update with fallback model","value":{"system_prompt":"You are a reliable assistant.","user_prompt":"Process: {input}","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","annotation":"Added fallback for reliability"}}}}}},"responses":{"200":{"description":"Task updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"},"examples":{"Update task metadata":{"summary":"Update task metadata","value":{"id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","name":"Support Ticket Triage","description":"Classifies inbound support tickets by category and priority, and drafts a one-line summary for the on-call agent.","enabled":true,"public":false,"exposed_to_agents":true,"output_modality":"json","task_run_visibility":"editors_and_owners","created":"2026-07-20T09:14:32Z","modified":"2026-07-25T16:20:05Z","access_token":"TASK_ACCESS_TOKEN_REDACTED","active_revisions":[{"task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","weight":1.0}],"revisions":[{"id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","system_prompt":"You are a support triage assistant for a B2B SaaS helpdesk. Read each ticket and classify it accurately so it reaches the right team quickly.","user_prompt":"Ticket subject: {subject}\n\nTicket body: {body}\n\nCustomer plan: {plan}","llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","llm_config":{"temperature":0.2},"output_format":{"category":{"type":"str","description":"The team best suited to handle this ticket","options":["account","billing","feature_request","technical"]},"priority":{"type":"str","description":"How urgently the ticket needs a response","options":["high","low","medium","urgent"]},"summary":{"type":"str","description":"One-sentence summary of the customer's issue"}},"file_input_mode":"none","optimise_images":true,"test":false,"input_processors":[],"annotation":"Initial production revision","task_mcp_tool_ids":[],"integration_tool_ids":[],"integration_bindings":[],"active":true,"created":"2026-07-20T09:14:32Z","modified":"2026-07-20T09:14:32Z","tags":[],"input_params":["subject","body","plan"],"llm_model":{"id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","provider":"Anthropic","vendor":"anthropic","name":"claude-sonnet-5","alias":"Claude Sonnet 5","description":"Balanced reasoning and speed for structured classification and extraction tasks.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":true,"max_context_window":200000,"model_params":{"temperature":{"type":"number","default":0.3,"maximum":1.0,"minimum":0.0,"description":"Controls randomness in the output. Lower values make output more focused and deterministic."}},"created":"2026-01-05T00:00:00Z","modified":"2026-01-05T00:00:00Z","llm_model_comments":[]}},{"id":"019f8a06-aa82-7da7-b159-8bb1d36bab06","system_prompt":"You are a support triage assistant for a B2B SaaS helpdesk. Classify each ticket, flag churn risk, and route it to the right team quickly.","user_prompt":"Ticket subject: {subject}\n\nTicket body: {body}\n\nCustomer plan: {plan}","llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","llm_config":{"temperature":0.2},"output_format":{"category":{"type":"str","description":"The team best suited to handle this ticket","options":["account","billing","feature_request","technical"]},"priority":{"type":"str","description":"How urgently the ticket needs a response","options":["high","low","medium","urgent"]},"summary":{"type":"str","description":"One-sentence summary of the customer's issue"},"churn_risk":{"type":"bool","description":"True if the customer shows signs of churn risk"}},"file_input_mode":"none","optimise_images":true,"test":false,"input_processors":[],"annotation":"Added churn-risk signal to prioritization","task_mcp_tool_ids":[],"integration_tool_ids":[],"integration_bindings":[],"active":false,"created":"2026-07-25T16:20:00Z","modified":"2026-07-25T16:20:00Z","tags":[],"input_params":["subject","body","plan"],"llm_model":{"id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","provider":"Anthropic","vendor":"anthropic","name":"claude-sonnet-5","alias":"Claude Sonnet 5","description":"Balanced reasoning and speed for structured classification and extraction tasks.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":true,"max_context_window":200000,"model_params":{"temperature":{"type":"number","default":0.3,"maximum":1.0,"minimum":0.0,"description":"Controls randomness in the output. Lower values make output more focused and deterministic."}},"created":"2026-01-05T00:00:00Z","modified":"2026-01-05T00:00:00Z","llm_model_comments":[]}}],"tags":[],"shared_with_project":false}}}}},"headers":{"X-New-Revision-ID":{"description":"ID of newly created revision (if task_revision was provided)","schema":{"type":"string","format":"uuid"}},"X-New-Revision-created":{"description":"Whether a new revision was created","schema":{"type":"string","enum":["true","false"]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid task configuration"}}},"description":"Bad Request - Invalid task configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatetask"},"examples":{"task_edit":{"summary":"Missing edit on task","value":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}}}},"description":"Forbidden - insufficient permission for this operation"},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task or referenced resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_or_referenced_resource [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_or_referenced_resource","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to update task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update an existing Task with new configuration or create a new revision.\n\nWhen updating a Task, you can:\n1. Modify basic Task properties (name, description, enabled status, task_run_visibility)\n2. Create a new revision with updated prompts, models, and configuration (including fallback models)\n3. Manage active revisions and their traffic weights for A/B testing\n4. Update tags for the Task or specific revisions\n\nTask Run Visibility Control:\n- Update `task_run_visibility` to control who can view all task runs\n- Options: `owner_only`, `editors_and_owners`, `all_viewers`\n\nFallback Model Support:\n- Configure `fallback_llm_model_id` and `fallback_llm_config` for automatic failover\n- Improves reliability when primary model encounters errors or rate limits\n\nFor `integration_bindings`, omission inherits the prior revision and an empty\narray removes every binding. Use a source `binding_id` to preserve a read-only\n`fixed_connection` binding. `integration_tool_ids` is deprecated.\n\nNote: Creating a new revision does not automatically make it active. Use the active_revisions field to control which revisions receive traffic."},"get":{"tags":["Tasks"],"summary":"Get Task Details","operationId":"getTask","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"revision_tag_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Revision Tag Id"},"description":"Filter task_revisions by tag ID."},{"name":"include_tests","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"title":"Include Tests"},"description":"Include test revisions"}],"responses":{"200":{"description":"Task details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"},"example":{"id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","name":"Support Ticket Triage","description":"Classifies inbound support tickets by category and priority, and drafts a one-line summary for the on-call agent.","enabled":true,"public":false,"exposed_to_agents":true,"output_modality":"json","task_run_visibility":"editors_and_owners","created":"2026-07-20T09:14:32Z","modified":"2026-07-25T16:20:05Z","access_token":"TASK_ACCESS_TOKEN_REDACTED","active_revisions":[{"task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","weight":1.0}],"revisions":[{"id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","system_prompt":"You are a support triage assistant for a B2B SaaS helpdesk. Read each ticket and classify it accurately so it reaches the right team quickly.","user_prompt":"Ticket subject: {subject}\n\nTicket body: {body}\n\nCustomer plan: {plan}","llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","llm_config":{"temperature":0.2},"output_format":{"category":{"type":"str","description":"The team best suited to handle this ticket","options":["account","billing","feature_request","technical"]},"priority":{"type":"str","description":"How urgently the ticket needs a response","options":["high","low","medium","urgent"]},"summary":{"type":"str","description":"One-sentence summary of the customer's issue"}},"file_input_mode":"none","optimise_images":true,"test":false,"input_processors":[],"annotation":"Initial production revision","task_mcp_tool_ids":[],"integration_tool_ids":[],"integration_bindings":[],"active":true,"created":"2026-07-20T09:14:32Z","modified":"2026-07-20T09:14:32Z","tags":[],"input_params":["subject","body","plan"],"llm_model":{"id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","provider":"Anthropic","vendor":"anthropic","name":"claude-sonnet-5","alias":"Claude Sonnet 5","description":"Balanced reasoning and speed for structured classification and extraction tasks.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":true,"max_context_window":200000,"model_params":{"temperature":{"type":"number","default":0.3,"maximum":1.0,"minimum":0.0,"description":"Controls randomness in the output. Lower values make output more focused and deterministic."}},"created":"2026-01-05T00:00:00Z","modified":"2026-01-05T00:00:00Z","llm_model_comments":[]}},{"id":"019f8a06-aa82-7da7-b159-8bb1d36bab06","system_prompt":"You are a support triage assistant for a B2B SaaS helpdesk. Classify each ticket, flag churn risk, and route it to the right team quickly.","user_prompt":"Ticket subject: {subject}\n\nTicket body: {body}\n\nCustomer plan: {plan}","llm_model_id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","llm_config":{"temperature":0.2},"output_format":{"category":{"type":"str","description":"The team best suited to handle this ticket","options":["account","billing","feature_request","technical"]},"priority":{"type":"str","description":"How urgently the ticket needs a response","options":["high","low","medium","urgent"]},"summary":{"type":"str","description":"One-sentence summary of the customer's issue"},"churn_risk":{"type":"bool","description":"True if the customer shows signs of churn risk"}},"file_input_mode":"none","optimise_images":true,"test":false,"input_processors":[],"annotation":"Added churn-risk signal to prioritization","task_mcp_tool_ids":[],"integration_tool_ids":[],"integration_bindings":[],"active":false,"created":"2026-07-25T16:20:00Z","modified":"2026-07-25T16:20:00Z","tags":[],"input_params":["subject","body","plan"],"llm_model":{"id":"019f6a00-9e3d-7c42-8f1a-2a5c9d4e7b01","provider":"Anthropic","vendor":"anthropic","name":"claude-sonnet-5","alias":"Claude Sonnet 5","description":"Balanced reasoning and speed for structured classification and extraction tasks.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":true,"max_context_window":200000,"model_params":{"temperature":{"type":"number","default":0.3,"maximum":1.0,"minimum":0.0,"description":"Controls randomness in the output. Lower values make output more focused and deterministic."}},"created":"2026-01-05T00:00:00Z","modified":"2026-01-05T00:00:00Z","llm_model_comments":[]}}],"tags":[],"shared_with_project":false}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid task ID format"}}},"description":"Bad Request - Invalid task ID format\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettask"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve detailed information about a specific Task.\n\nReturns the complete Task configuration including:\n- Basic properties (name, description, enabled status)\n- All revisions with their prompts and configurations\n- Currently active revisions and their traffic weights\n- Associated tags and metadata"},"delete":{"tags":["Tasks"],"summary":"Delete Task","operationId":"deleteTask","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."}],"responses":{"200":{"description":"Task deleted successfully","content":{"application/json":{"schema":{"type":"null"},"example":null}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletetask"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"409":{"description":"Task is used by an active TaskAgent share and cannot be deleted until that share is revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"description":"Delete a task and all its associated data.\n\nThis operation will permanently remove:\n- The task configuration\n- All task runs and their outputs\n- Associated documents and files\n- Task history and analytics\n\nThe deletion is irreversible. Ensure you have exported any important data before deletion.\n\nTasks used by an active TaskAgent share cannot be deleted until that\nTaskAgent share is revoked.\n\n**Note**: You must have edit permission on the task to delete it."}},"/org/{org_id}/project/{project_id}/task/{task_id}/token_report":{"get":{"tags":["Tasks"],"summary":"Fetch Token Report","operationId":"getTaskTokenReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"description":"Start date for the report (e.g., '2023-06-01', '24 hours ago', 'yesterday')."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"description":"End date for the report (e.g., '2023-06-30', 'now', 'today')."},{"name":"show_reporting_group","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Show Reporting Group"},"description":"If true, include reporting group in the report."}],"responses":{"200":{"description":"Successfully retrieved token usage report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRunTokenReport"},"example":{"task_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","date_range":{"start":"2024-01-01T00:00:00Z","end":"2024-01-31T23:59:59Z"},"total_input_tokens":10000,"total_output_tokens":5000,"total_tokens":15000,"total_task_runs":100,"task_revisions":[{"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f2","total_input_tokens":6000,"total_output_tokens":3000,"total_tokens":9000,"total_task_runs":60},{"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f3","total_input_tokens":4000,"total_output_tokens":2000,"total_tokens":6000,"total_task_runs":40}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid date format or range"}}},"description":"Bad Request - Invalid date format or range\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettasktokenreport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve token usage data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve aggregate token usage statistics for a specific task.\n\nThis report returns:\n- Total input, output, and combined tokens across the filtered time range\n- A per-revision token breakdown\n- Optional segmentation by reporting group\n\nParameters:\n- `start_date`: Filter data from this date onward\n- `end_date`: Filter data up to this date\n- `show_reporting_group`: Include reporting group segmentation in the per-revision breakdown"}},"/org/{org_id}/project/{project_id}/task/{task_id}/usage_report":{"get":{"tags":["Tasks"],"summary":"Fetch Usage Report","operationId":"getTaskUsageReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"aggregation","in":"query","required":false,"schema":{"enum":["day","week"],"type":"string","default":"day","title":"Aggregation"},"description":"The aggregation level for the report. Can be either 'day' or 'week'."},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UsageReportStatus","default":"ALL"},"description":"Run outcome filter for the report. Can be ALL, SUCCESS, or FAIL."}],"responses":{"200":{"description":"Usage report retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRunUsageReport"},"example":{"task_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","date_range":{"start":"2024-01-14T15:00:00+00:00","end":"2024-01-15T15:00:00+00:00"},"aggregation":"day","status":"ALL","task_revisions":[{"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f2","data":{"2024-01-14 15:00:00":24,"2024-01-14 16:00:00":31}}],"total_counts":{"2024-01-14 15:00:00":24,"2024-01-14 16:00:00":31}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid aggregation parameter"}}},"description":"Bad Request - Invalid aggregation parameter\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskusagereport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to process usage data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve usage statistics for task executions.\n\nThis endpoint provides detailed usage data about task runs, including:\n- Number of executions over time, bucketed by hour (see `aggregation` below)\n- A per-revision breakdown alongside the combined `total_counts`\n- Optional filtering to only successful or only failed runs\n\nUse this data to:\n1. Monitor task usage patterns\n2. Track execution success rates\n3. Analyze usage trends\n4. Plan capacity and scaling\n\n**Aggregation window:**\n- `aggregation=day` (default): last 24 hours, bucketed hourly\n- `aggregation=week`: last 7 days, bucketed daily"}},"/org/{org_id}/project/{project_id}/task/{task_id}/timing_report":{"get":{"tags":["Tasks"],"summary":"Fetch Timing Report","operationId":"getTaskTimingReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"description":"Start date for the report (e.g., '2023-06-01', '24 hours ago', 'yesterday')."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"description":"End date for the report (e.g., '2023-06-30', 'now', 'today')."},{"name":"aggregation","in":"query","required":false,"schema":{"enum":["hour","day"],"type":"string","default":"hour","title":"Aggregation"},"description":"The aggregation level for the report. Can be either 'hour' or 'day'"}],"responses":{"200":{"description":"Timing report retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRunTimingReport"},"example":{"task_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","date_range":{"start":"2024-03-14T15:00:00Z","end":"2024-03-15T15:00:00Z"},"aggregation":"hour","total_task_runs":{"2024-03-14 15:00:00":150,"2024-03-14 16:00:00":165},"task_revisions":[{"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f2","data":{"2024-03-14 15:00:00":{"avg_llm_call_timing":2.45,"total_task_runs":150},"2024-03-14 16:00:00":{"avg_llm_call_timing":2.38,"total_task_runs":165}}}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid date format or range"}}},"description":"Bad Request - Invalid date format or range\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettasktimingreport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to process timing data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve average LLM call timing for task executions over time.\n\nThis endpoint returns:\n- Average `llm_call_timing` values grouped by hour or day\n- Total task run counts for each time bucket\n- A per-revision breakdown, including test revisions\n\nDefaults:\n- `aggregation=hour` returns the last 24 hours when no date range is provided\n- `aggregation=day` returns the last 7 days when no date range is provided"}},"/org/{org_id}/project/{project_id}/task/{task_id}/credit_report":{"get":{"tags":["Tasks"],"summary":"Fetch Credit Report","operationId":"getTaskCreditReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"description":"Start date for the report (e.g., '2023-06-01', '24 hours ago', 'yesterday')."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"description":"End date for the report (e.g., '2023-06-30', 'now', 'today')."},{"name":"show_reporting_group","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Show Reporting Group"},"description":"If true, include reporting group in the report."}],"responses":{"200":{"description":"Successfully retrieved credit usage report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRunCreditReport"},"example":{"task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","task_revisions":[{"task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","total_credits":"142.50","total_task_runs":138}],"total_credits":"142.50","total_task_runs":138,"date_range":{"start":"2026-06-27T00:00:00Z","end":"2026-07-27T00:00:00Z"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid date format or range"}}},"description":"Bad Request - Invalid date format or range\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskcreditreport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve credit usage data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve aggregate credit usage statistics for a specific task.\n\nThis report returns:\n- Total `charged_credits` across the filtered time range\n- A per-revision credit breakdown\n- Optional segmentation by reporting group\n\nCredit reports are limited to a maximum 3-month lookback window. If `start_date`\nis omitted, the report defaults to the earliest permitted date."}},"/org/{org_id}/project/{project_id}/task/{task_id}/run":{"post":{"tags":["Tasks"],"summary":"Run Task","operationId":"runTask","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:run_task"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"revision_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"],"title":"Revision Id"},"description":"Optional Task Revision ID to use for execution. If not provided, an active revision will be selected based on traffic weights."},{"name":"revision_tag","in":"query","required":false,"schema":{"anyOf":[{"type":"string","examples":["production","staging","experimental"]},{"type":"null"}],"examples":["latest","stable"],"title":"Revision Tag"},"description":"Optional Task Revision Tag to use for execution. If not provided, an active revision will be selected based on traffic weights."},{"name":"reporting_group","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Reporting Group"},"description":"Optional reporting group name to associate with this task run"},{"name":"use_fallback_model","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Use Fallback Model"},"description":"If true, immediately use the fallback model instead of the primary model. Requires the task to have a fallback model configured."}],"responses":{"200":{"description":"Task executed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRun"},"examples":{"Single ticket triage":{"summary":"Single ticket triage","value":{"id":"019f8a04-8e60-7b85-af37-6e9fb14d8fa4","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","model_name":"claude-sonnet-5","task_name":"Support Ticket Triage","output_modality":"json","response":{"category":"billing","priority":"high","summary":"Customer was double-charged for their Pro plan renewal and wants a refund."},"run_data":{"mcp_tool_calls":[],"integration_tool_calls":[],"submitted":{"subject":"Charged twice this month","body":"I was billed twice for my Pro subscription on the 3rd and the 5th. Please refund the duplicate charge.","plan":"Pro"}},"files":[],"is_error":false,"llm_retries":0,"used_fallback_model":false,"user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","created":"2026-07-24T10:02:17Z","input_tokens":186,"output_tokens":42,"total_tokens":228,"input_processor_timing":0.00015282,"llm_call_timing":1.346,"charged_credits":"1","input_processor_charged_credits":"0"}}}}},"headers":{"X-Task-Run-ID":{"description":"Unique identifier for this task execution","schema":{"type":"string","format":"uuid"}},"X-Task-Revision-ID":{"description":"ID of the task revision used for execution","schema":{"type":"string","format":"uuid"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid task input format"}}},"description":"Bad Request - Invalid task input format\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Runtask"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have run_task permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"run_task"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid task input parameters\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid task input parameters","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"402":{"description":"Payment Required - the organization cannot execute tasks\n\n**Common causes:**\n- `No credits remaining` - the account's credit balance is exhausted\n- `Trial expired` - the trial period ended\n- `Subscription cancelled` - the subscription is cancelled, or is cancelling and past its end date\n- `Payment required - grace period expired` - payment failed and the grace period has passed\n\n**Resolution:** Top up credits or update the subscription, then retry the run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"No credits remaining. Please upgrade or top-up so your tasks continue to run uninterrupted."}}}},"404":{"description":"Task or revision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_or_revision [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_or_revision","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to execute task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["task_input"],"properties":{"task_input":{"type":"object","description":"Key-value pairs mapping variable names to their values. Keys must match the variable placeholders in your task's user_prompt.","additionalProperties":true},"task_files":{"type":"array","description":"Optional base64-encoded files to include with the task run","items":{"type":"object","properties":{"filename":{"type":"string"},"content":{"type":"string","format":"byte"}}}},"task_reference":{"type":"string","maxLength":64,"description":"Optional reference ID for tracking this task run"}}},"examples":{"basic":{"summary":"Single ticket triage","description":"Run the Support Ticket Triage task against one inbound ticket","value":{"task_input":{"subject":"Charged twice this month","body":"I was billed twice for my Pro subscription on the 3rd and the 5th. Please refund the duplicate charge.","plan":"Pro"}}},"multiple_inputs":{"summary":"Urgent technical ticket","description":"Run the same task against a different ticket to see priority and category shift","value":{"task_input":{"subject":"Webhooks failing with 500","body":"All our webhook deliveries have been failing with a 500 error since 9am. This is blocking our production sync.","plan":"Enterprise"}}},"with_reference":{"summary":"Follow-up run with task_reference","description":"Attach your own tracking ID to a follow-up run on the same ticket using task_reference","value":{"task_input":{"subject":"Charged twice this month","body":"Update: I checked my statement again and the two charges were for different months, not a duplicate. Please disregard.","plan":"Pro"},"task_reference":"ticket-482913"}}}}}},"description":"Run a task with the specified inputs and receive structured output.\n\nThis endpoint executes the task using its active revision(s) and returns the results. Key features:\n1. Automatic revision selection based on traffic weights\n2. Structured output matching the task's output modality:\n   - `json`: Structured JSON responses\n   - `image`: Generated image files (PNG, JPEG)\n   - `audio`: Generated audio files\n   - `pdf`: Formatted PDF documents\n   - `text`: Plain text responses\n   - `csv`: CSV data files\n3. Execution metadata (tokens, timing, credits charged)\n4. Support for file uploads when required\n5. Automatic fallback to backup model on primary model failures\n6. Optional manual fallback model triggering\n7. Reporting group tracking for analytics and billing\n\n**Request Body:**\n\n⚠️ **IMPORTANT**: The request body must use the `task_input` field (not `input_params`):\n\n```json\n{\n  \"task_input\": {\n    \"variable_name\": \"value to substitute in user_prompt\"\n  }\n}\n```\n\nThe keys in `task_input` should match the `{variable}` placeholders defined in your task's `user_prompt`. For example, if your prompt contains `{text}` and `{language}`, your request should be:\n\n```json\n{\n  \"task_input\": {\n    \"text\": \"Hello world\",\n    \"language\": \"Spanish\"\n  }\n}\n```\n\n**Required:**\n- `task_input` object with parameters matching the task's prompt variables\n- File upload when task `file_input_mode` is not `none`\n\n**Optional Body Fields:**\n- `task_reference` to attach your own tracking ID to this run\n- `task_files` for base64-encoded file uploads\n\n**Optional Query Parameters:**\n- `revision_id` or `revision_tag` for testing or comparison\n- `reporting_group` name for segmented analytics\n- `use_fallback_model` flag to manually trigger fallback\n\nThe response includes:\n- Structured output matching the task's output_format\n- Execution metadata (tokens used, timing, credits charged)\n- Fallback model usage information if applicable\n- Input data for audit purposes\n- References to any processed files\n\n**Common Use Cases:**\n\n*A/B Testing Revisions:*\nCompare different prompt versions by explicitly specifying `revision_id` or `revision_tag` for each request, then analyze results.\n\n*Gradual Rollouts:*\nConfigure traffic weights on revisions to gradually shift traffic from an old prompt to a new one while monitoring performance.\n\n*Fallback Model Strategy:*\nUse `use_fallback_model=true` to manually switch to the backup model during known primary model outages or rate limits.\n\n*Analytics Segmentation:*\nPass `reporting_group` to track metrics by customer, feature, or experiment cohort for billing and performance analysis."},"get":{"tags":["Tasks"],"summary":"List Task Runs","operationId":"getTaskRuns","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"page_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["success","error"],"type":"string"},{"type":"null"}],"title":"Status"},"description":"Filter by task run status"},{"name":"task_revision_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"],"title":"Task Revision Id"},"description":"Filter task runs by revision ID"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"description":"Start date for the listing (e.g., '2023-06-01', '24 hours ago', 'yesterday'). Defaults to 7 days before end_date or now."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"description":"End date for the listing (e.g., '2023-06-30', 'now', 'today'). Defaults to now."},{"name":"include_event_trigger_id","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Event Trigger Id"},"description":"If true, include event_trigger_id for each task run in results."}],"responses":{"200":{"description":"Successfully retrieved task runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskRun_"},"example":{"results":[{"id":"019f8a05-9f71-7c96-b048-7fa0c25f9ab5","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","model_name":"claude-sonnet-5","task_name":"Support Ticket Triage","output_modality":"json","response":{"category":"technical","priority":"urgent","summary":"API integration is returning 500 errors on all webhook deliveries since this morning."},"run_data":{"mcp_tool_calls":[],"integration_tool_calls":[],"submitted":{"subject":"Webhooks failing with 500","body":"All our webhook deliveries have been failing with a 500 error since 9am. This is blocking our production sync.","plan":"Enterprise"}},"files":[],"is_error":false,"llm_retries":1,"used_fallback_model":true,"primary_failure_reason":"Primary model rate limited (429)","fallback_llm_model_id":"019f6a01-0f4e-7d53-9a2c-6b7d8e9fa102","user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_basis":"trigger_owner","execution_surface":"webhook","execution_source_id":"019f8a03-7d5f-7084-9e26-5d8fa03c7e93","created":"2026-07-24T11:47:03Z","input_tokens":201,"output_tokens":47,"total_tokens":248,"input_processor_timing":0.0001671,"llm_call_timing":2.91,"charged_credits":"1.35","input_processor_charged_credits":"0.00"},{"id":"019f8a04-8e60-7b85-af37-6e9fb14d8fa4","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","model_name":"claude-sonnet-5","task_name":"Support Ticket Triage","output_modality":"json","response":{"category":"billing","priority":"high","summary":"Customer was double-charged for their Pro plan renewal and wants a refund."},"run_data":{"mcp_tool_calls":[],"integration_tool_calls":[],"submitted":{"subject":"Charged twice this month","body":"I was billed twice for my Pro subscription on the 3rd and the 5th. Please refund the duplicate charge.","plan":"Pro"}},"files":[],"is_error":false,"llm_retries":0,"used_fallback_model":false,"user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_basis":"direct_user","execution_surface":"task_api","execution_source_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","created":"2026-07-24T10:02:17Z","input_tokens":186,"output_tokens":42,"total_tokens":228,"input_processor_timing":0.00015282,"llm_call_timing":1.346,"charged_credits":"1.00","input_processor_charged_credits":"0.00"}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid parameters"}}},"description":"Bad Request - Invalid parameters\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskruns"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request parameters\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request parameters","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task or revision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_or_revision [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_or_revision","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve task runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve a paginated list of task runs for a specific task.\n\nTask runs provide an audit trail of all task executions, including:\n- Input parameters used\n- Execution status and timing\n- Resource usage metrics (tokens, credits)\n- Output results\n- Error information for failed runs\n- Fallback model usage information\n- Execution identity and entry-point information\n\nThis endpoint supports:\n- Pagination using cursor-based navigation\n- Filtering by a created-time date range\n- Filtering by task revision\n- Filtering by status (success/error)\n- Sorting by creation time (newest first)\n\nCommon use cases:\n1. Monitoring task execution history\n2. Auditing task usage and performance\n3. Debugging task behavior across multiple runs\n4. Analyzing task output patterns\n5. Tracking fallback model usage and reliability"}},"/org/{org_id}/project/{project_id}/task/{task_id}/iam/members":{"get":{"tags":["Tasks"],"summary":"IAM - List Task Members","description":"Lists all members that have been granted direct access to the task.","operationId":"task_iam_org_org_id_project_project_id_task_task_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view","task:view_members"]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Task members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Iam Org Org Id Project Project Id Task Task Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task/{task_id}/iam/members/{member}":{"get":{"tags":["Tasks"],"summary":"IAM - Lookup Task Member","description":"Retrieve a specific member that has been granted direct access to the task.","operationId":"task_iam_org_org_id_project_project_id_task_task_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view","task:view_members"]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Task member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Iam Org Org Id Project Project Id Task Task Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Tasks"],"summary":"IAM - Update Task Member","description":"Update the roles that a member holds on the task.","operationId":"task_iam_org_org_id_project_project_id_task_task_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Task member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Task Iam Org Org Id Project Project Id Task Task Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Iam Org Org Id Project Project Id Task Task Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task/{task_id}/iam/test":{"post":{"tags":["Tasks"],"summary":"IAM - Test Task Permissions","description":"Test the permissions that the caller (or another subject) holds on the task.","operationId":"task_iam_org_org_id_project_project_id_task_task_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Task permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Task Iam Org Org Id Project Project Id Task Task Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Iam Org Org Id Project Project Id Task Task Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task-agent":{"get":{"tags":["Task Agents"],"summary":"List Task Agents","description":"List all Task Agents configured for the project.\n\nReturns a paginated list of Task Agents with their root metadata and embedded\nrevision history. Runtime configuration such as instructions, models, and tools\nis stored on each revision.","operationId":"listTaskAgents","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"Pagination cursor"},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"Max results per page"},{"name":"seven_day_summary","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Seven Day Summary"},"description":"When true, include a seven day summary of visible run count, average charged credits, and average duration for each returned TaskAgent."}],"responses":{"200":{"description":"Successfully retrieved Task Agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskAgentRead_"},"example":{"results":[{"id":"019df849-e106-3301-5894-291b4c9c6cab","name":"Support Triage Agent","active_revision":{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2026-06-12T09:30:00Z","modified":"2026-06-12T09:30:00Z"},"revisions":[{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","description":"Triages inbound client support emails, looks up the client's account, and drafts a reply.","instruction":"You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message: (1) run the Customer Support Analyzer to classify the sender's sentiment and issue category, (2) look up the client's account in the Customer Database sheet using their email address to confirm their plan, billing status, and any existing notes before you say anything about their account, (3) draft a reply that directly answers what they asked, references specific figures from the account lookup rather than the analyzer's summary, and matches a warm but professional tone, and (4) once a team member confirms the reply, log a one-line resolution note back to the Tickets sheet so the team can see the case was handled. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day. If the account lookup returns no match for the sender's email, say so plainly in the draft and ask the client to confirm the email address on file rather than guessing.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[{"id":"019df7a2-44a0-7ee9-8876-25aa7a902f38","task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":false,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"},{"id":"019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb","task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","revision_strategy":"pinned","task_name":"Draft Support Reply","order":1,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"}],"integrations":[{"id":"019ebb2a-b9c0-7af9-b42d-e9cd2819667d","project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_type":"google_sheets","integration_name":"Customer Database","order":0,"enabled":true,"credential_policy":"project_default","allowed_tool_ids":["019df7a2-44a0-7b09-afd0-c59cbc20126d","019df7a2-44a0-7923-9ea9-87be4ba93be9"],"default_action_mode":"auto_run","default_approval_percent":100,"default_rejection_behavior":"end_run","tool_action_modes":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":"require_approval"},"tool_approval_percents":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":10},"tool_rejection_behaviors":{},"provision_source":"manual","tool_count":2}],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"max_turns":50,"active":true,"created":"2026-06-12T09:30:00Z","modified":"2026-06-12T09:30:00Z"}],"task_agent_run_visibility":"editors_and_owners","shared_with_project":true,"is_deleted":false,"created":"2026-05-05T10:15:00Z","modified":"2026-06-12T09:30:00Z"},{"id":"019fa2da-4790-7eeb-a8e7-a8f225f87026","name":"Invoice Reconciliation Agent","active_revision":{"id":"019fa2da-4790-7498-a387-8196969ee341","task_agent_id":"019fa2da-4790-7eeb-a8e7-a8f225f87026","created":"2026-07-01T08:00:00Z","modified":"2026-07-01T08:00:00Z"},"revisions":[{"id":"019fa2da-4790-7498-a387-8196969ee341","task_agent_id":"019fa2da-4790-7eeb-a8e7-a8f225f87026","description":"Matches supplier invoices to purchase orders.","instruction":"Reconcile incoming supplier invoices against open purchase orders and flag mismatches over £25 for manual review.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[],"integrations":[],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"active":true,"created":"2026-07-01T08:00:00Z","modified":"2026-07-01T08:00:00Z"}],"task_agent_run_visibility":"owner_only","shared_with_project":false,"is_deleted":false,"created":"2026-07-01T08:00:00Z","modified":"2026-07-01T08:00:00Z"}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid pagination"}}},"description":"Bad Request - Invalid pagination\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskagents"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"post":{"tags":["Task Agents"],"summary":"Create Task Agent","description":"Create a new Task Agent for the project.\n\nTask Agents orchestrate multiple Tasks as task tools using LLM-powered reasoning.\n\nThe request creates the root Task Agent and its initial active revision. Runtime\nconfiguration such as instructions, models, and tools is stored on revisions.\nReferenced MCP servers and Integrations require view access. Inaccessible\nattachments are concealed as not found.","operationId":"createTaskAgent","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_task_agent"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentCreate"},"examples":{"minimal":{"summary":"Minimal agent","description":"`name`, `instruction` and `llm_model_id` are the only required fields.","value":{"name":"Support Triage Agent","instruction":"Read the ticket, decide which team owns it, and draft a concise reply.","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41"}},"with_execution_settings":{"summary":"With mode and turn limit","description":"`mode` accepts `agentic` or `sequential`. `max_turns` caps reasoning turns for a single run.","value":{"name":"Support Triage Agent","description":"Triages inbound support tickets and drafts a first response.","instruction":"Read the ticket, decide which team owns it, and draft a concise reply.","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","mode":"agentic","max_turns":8}},"with_integration":{"summary":"Agent with a project connection","value":{"name":"Support Triage Agent","instruction":"Look up the customer before replying.","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","integrations":[{"project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","credential_policy":"project_default","allowed_tool_ids":["019df7a2-44a0-7b09-afd0-c59cbc20126d"],"default_action_mode":"require_approval","tool_approval_percents":{"019df7a2-44a0-7b09-afd0-c59cbc20126d":10}}]}}}}}},"responses":{"201":{"description":"Task Agent created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentRead"},"examples":{"Minimal agent":{"summary":"Minimal agent","value":{"id":"019df849-e106-3301-5894-291b4c9c6cab","name":"Support Triage Agent","active_revision":{"id":"019df7a2-44a0-7d66-b496-52c6c197bca1","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z"},"revisions":[{"id":"019df7a2-44a0-7d66-b496-52c6c197bca1","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","description":"Triages inbound client support emails and drafts a reply.","instruction":"You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message, run the Customer Support Analyzer to classify the sender's sentiment and issue category, then draft a reply that directly answers what they asked in a warm but professional tone. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[{"id":"019df7a2-44a0-7ee9-8876-25aa7a902f38","task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":false,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"},{"id":"019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb","task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","revision_strategy":"pinned","task_name":"Draft Support Reply","order":1,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"}],"integrations":[],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"max_turns":50,"active":true,"created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z"}],"task_agent_run_visibility":"owner_only","shared_with_project":false,"is_deleted":false,"created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid configuration"}}},"description":"Bad Request - Invalid configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskagent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_task_agent permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_task_agent"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project or referenced attachment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project_or_referenced_attachment [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project_or_referenced_attachment","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to create Task Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/timing_report":{"get":{"tags":["Task Agents"],"summary":"Get Project TaskAgent Timing Report","operationId":"getProjectTaskAgentTimingReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Id"},"description":"Filter to a specific TaskAgent"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Date"},"description":"Report start timestamp"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date"},"description":"Report end timestamp"},{"name":"aggregation","in":"query","required":false,"schema":{"enum":["hour","day"],"type":"string","default":"hour","title":"Aggregation"},"description":"Time bucket granularity. Can be either 'hour' or 'day'."}],"responses":{"200":{"description":"Project TaskAgent timing report details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectTaskAgentTimingReport"},"example":{"project_id":"0190a234-9876-5432-10ab-cdef01234567","date_range":{"start":"2026-07-24T08:00:00Z","end":"2026-07-24T11:00:00Z"},"aggregation":"hour","data":{"2026-07-24T08:00:00":{"avg_duration_ms":0.0,"total_runs":0},"2026-07-24T09:00:00":{"avg_duration_ms":0.0,"total_runs":0},"2026-07-24T10:00:00":{"avg_duration_ms":7582.0,"total_runs":1},"2026-07-24T11:00:00":{"avg_duration_ms":0.0,"total_runs":0}},"total_runs":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojecttaskagenttimingreport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to build the timing report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Aggregate timing across the TaskAgent runs visible to the caller in this project.\n\nScope the report with `task_agent_id`, `start_date` and `end_date`. `aggregation` selects the bucket granularity: `hour` (the default) covers the last 24 hours, `day` the last seven days.\n\n`data` contains every bucket in the window, including empty ones, and `avg_duration_ms` is the mean wall-clock duration of the runs in that bucket."}},"/org/{org_id}/project/{project_id}/task-agent/usage_report":{"get":{"tags":["Task Agents"],"summary":"Get Project TaskAgent Usage Report","operationId":"getProjectTaskAgentUsageReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Id"},"description":"Filter to a specific TaskAgent"},{"name":"aggregation","in":"query","required":false,"schema":{"enum":["day","week"],"type":"string","default":"day","title":"Aggregation"},"description":"Time bucket granularity. Can be either 'day' or 'week'."},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UsageReportStatus","default":"ALL"},"description":"Run outcome filter for the report. Can be ALL, SUCCESS, or FAIL."}],"responses":{"200":{"description":"Project TaskAgent usage report details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectTaskAgentUsageReport"},"example":{"project_id":"0190a234-9876-5432-10ab-cdef01234567","date_range":{"start":"2026-07-17T10:00:00.000000Z","end":"2026-07-24T10:00:00.000000Z"},"aggregation":"week","status":"ALL","data":{"2026-07-17T00:00:00":0,"2026-07-18T00:00:00":0,"2026-07-19T00:00:00":0,"2026-07-20T00:00:00":0,"2026-07-21T00:00:00":0,"2026-07-22T00:00:00":0,"2026-07-23T00:00:00":0,"2026-07-24T00:00:00":1},"total_runs":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojecttaskagentusagereport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to build the usage report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Visible TaskAgent run counts over time for this project.\n\nScope the report with `task_agent_id` and `status` (`ALL`, `SUCCESS` or `FAIL`). Unlike the timing report this endpoint has no `start_date`/`end_date`: the window is always relative to now, and `aggregation` chooses it — `day` (the default) returns the last 24 hours in hourly buckets, `week` the last seven days in daily buckets.\n\n`data` maps each bucket to a run count and contains every bucket in the window, including empty ones. `total_runs` is the sum across the window."}},"/org/{org_id}/project/{project_id}/task-agent/approval-request":{"get":{"tags":["Task Agents"],"summary":"List Project Task Agent Approval Requests","operationId":"listProjectTaskAgentApprovalRequests","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Id"},"description":"Filter by TaskAgent ID."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentApprovalRequestStatus"},{"type":"null"}],"title":"Status"},"description":"Filter by approval request status."},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"description":"Filter by TaskAgentRun ID."},{"name":"session_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"description":"Filter by ADK session ID."},{"name":"tool_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentToolSource"},{"type":"null"}],"title":"Tool Type"},"description":"Filter by tool source."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created After"},"description":"Filter approval requests created at/after this timestamp."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Before"},"description":"Filter approval requests created at/before this timestamp."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"Project Task Agent approval requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_ProjectTaskAgentApprovalRequestRead_"},"example":{"results":[{"id":"019fa2e2-2f00-71c7-aee7-539ab31cd302","project_id":"0190a234-9876-5432-10ab-cdef01234567","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_name":"Support Triage Agent","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_run_id":"019fa2e2-2f00-7be2-bcf0-f056f44f700a","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","invocation_id":"019fa2e2-2f00-7a54-9f70-cd49ad3571d2","function_call_id":"call-4f19a7c3e8b2","adk_event_id":"019fa2e2-2f00-77e0-a459-008f7d11e9f8","requested_by_user_id":"0190c234-1111-2222-3333-444444444444","requested_by_actor_type":"user","requester_is_decider":false,"tool_action_control_id":"019fa2e2-2f00-7d54-ab2e-0fd98d058991","action_mode_snapshot":"require_approval","tool_type":"integration","tool_name":"sheets_spreadsheets_values_append","status":"pending","created":"2026-07-27T09:22:41Z","modified":"2026-07-27T09:22:41Z","expires_at":"2026-07-27T10:22:41Z"}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid approval request filters"}}},"description":"Bad Request - Invalid approval request filters\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojecttaskagentapprovalrequests"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list project Task Agent approval requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List human approval requests for visible Task Agents in a project.\n\nApproval requests are visible through the same visibility rules as their linked\nTask Agent run. Pending requests may be returned as expired when their approval\nwindow has elapsed. This project-scoped list is compact and omits tool argument\npayloads, raw tool references, and full user records."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}":{"get":{"tags":["Task Agents"],"summary":"Get Task Agent","description":"Retrieve detailed information about a specific Task Agent.\n\nReturns root Task Agent metadata with embedded immutable revisions. Runtime\nconfiguration such as instructions, models, and tools is stored on each revision.","operationId":"getTaskAgent","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Agent Id"},"description":"The specific Task Agent to reference."}],"responses":{"200":{"description":"Task Agent details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentRead"},"example":{"id":"019df849-e106-3301-5894-291b4c9c6cab","name":"Support Triage Agent","active_revision":{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2026-06-12T09:30:00Z","modified":"2026-06-12T09:30:00Z"},"revisions":[{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","description":"Triages inbound client support emails, looks up the client's account, and drafts a reply.","instruction":"You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message: (1) run the Customer Support Analyzer to classify the sender's sentiment and issue category, (2) look up the client's account in the Customer Database sheet using their email address to confirm their plan, billing status, and any existing notes before you say anything about their account, (3) draft a reply that directly answers what they asked, references specific figures from the account lookup rather than the analyzer's summary, and matches a warm but professional tone, and (4) once a team member confirms the reply, log a one-line resolution note back to the Tickets sheet so the team can see the case was handled. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day. If the account lookup returns no match for the sender's email, say so plainly in the draft and ask the client to confirm the email address on file rather than guessing.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[{"id":"019df7a2-44a0-7ee9-8876-25aa7a902f38","task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":false,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"},{"id":"019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb","task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","revision_strategy":"pinned","task_name":"Draft Support Reply","order":1,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"}],"integrations":[{"id":"019ebb2a-b9c0-7af9-b42d-e9cd2819667d","project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_type":"google_sheets","integration_name":"Customer Database","order":0,"enabled":true,"credential_policy":"project_default","allowed_tool_ids":["019df7a2-44a0-7b09-afd0-c59cbc20126d","019df7a2-44a0-7923-9ea9-87be4ba93be9"],"default_action_mode":"auto_run","default_approval_percent":100,"default_rejection_behavior":"end_run","tool_action_modes":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":"require_approval"},"tool_approval_percents":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":10},"tool_rejection_behaviors":{},"provision_source":"manual","tool_count":2}],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"max_turns":50,"active":true,"created":"2026-06-12T09:30:00Z","modified":"2026-06-12T09:30:00Z"},{"id":"019df7a2-44a0-7d66-b496-52c6c197bca1","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","description":"Triages inbound client support emails and drafts a reply.","instruction":"You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message, run the Customer Support Analyzer to classify the sender's sentiment and issue category, then draft a reply that directly answers what they asked in a warm but professional tone. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[{"id":"019df7a2-44a0-7ee9-8876-25aa7a902f38","task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":false,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"},{"id":"019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb","task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","revision_strategy":"pinned","task_name":"Draft Support Reply","order":1,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"}],"integrations":[],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"max_turns":50,"active":false,"created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z"}],"task_agent_run_visibility":"editors_and_owners","shared_with_project":true,"is_deleted":false,"created":"2026-05-05T10:15:00Z","modified":"2026-06-12T09:30:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"post":{"tags":["Task Agents"],"summary":"Update Task Agent","description":"Update Task Agent metadata, create a new revision, or activate an existing revision.\n\nModifiable fields:\n- Root metadata: name and run visibility\n- Revision configuration: description, instruction, LLM models, execution mode,\n  memory settings, task tools, MCP servers, integrations, and skills\n- Activation: `active_revision_id`\n\nUpdating revision configuration creates a new inactive revision. Activate it with a\nseparate request that only includes `active_revision_id`.\n\nTo update task tools, pass a `task_tools` array. This performs a full replacement:\n- Omit the field to leave task tools unchanged\n- Pass an empty array to remove all task tools\n- Pass a new array to replace all task tools (array order = execution order)\n\nExample: the response below shows the Support Triage Agent right after adding\nthe Customer Database integration and refining `instruction` — `active_revision`\nstill points at the prior revision because activation is a separate call, and\nthe new revision appears in `revisions` with `active: false`.\n\nReferenced MCP servers and Integrations require view access. Inaccessible\nattachments are concealed as not found.","operationId":"updateTaskAgent","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentUpdate"},"examples":{"revise_configuration":{"summary":"Revise configuration","description":"Sending revision configuration creates a new inactive revision; activate it with a separate request.","value":{"description":"Triages inbound support tickets, drafts a reply, and escalates billing questions.","max_turns":12,"integrations":[{"project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","credential_policy":"project_default","allowed_tool_ids":["019df7a2-44a0-7b09-afd0-c59cbc20126d"]}]}},"activate_revision":{"summary":"Activate an existing revision","description":"Send `active_revision_id` on its own to activate a revision that already exists.","value":{"active_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4"}}}}}},"responses":{"200":{"description":"Task Agent updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentRead"},"examples":{"Revise configuration":{"summary":"Revise configuration","value":{"id":"019df849-e106-3301-5894-291b4c9c6cab","name":"Support Triage Agent","active_revision":{"id":"019df7a2-44a0-7d66-b496-52c6c197bca1","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z"},"revisions":[{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","description":"Triages inbound client support emails, looks up the client's account, and drafts a reply.","instruction":"You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message: (1) run the Customer Support Analyzer to classify the sender's sentiment and issue category, (2) look up the client's account in the Customer Database sheet using their email address to confirm their plan, billing status, and any existing notes before you say anything about their account, (3) draft a reply that directly answers what they asked, references specific figures from the account lookup rather than the analyzer's summary, and matches a warm but professional tone, and (4) once a team member confirms the reply, log a one-line resolution note back to the Tickets sheet so the team can see the case was handled. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day. If the account lookup returns no match for the sender's email, say so plainly in the draft and ask the client to confirm the email address on file rather than guessing.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[{"id":"019df7a2-44a0-7ee9-8876-25aa7a902f38","task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":false,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"},{"id":"019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb","task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","revision_strategy":"pinned","task_name":"Draft Support Reply","order":1,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"}],"integrations":[{"id":"019ebb2a-b9c0-7af9-b42d-e9cd2819667d","project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_type":"google_sheets","integration_name":"Customer Database","order":0,"enabled":true,"credential_policy":"project_default","allowed_tool_ids":["019df7a2-44a0-7b09-afd0-c59cbc20126d","019df7a2-44a0-7923-9ea9-87be4ba93be9"],"default_action_mode":"auto_run","default_approval_percent":100,"default_rejection_behavior":"end_run","tool_action_modes":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":"require_approval"},"tool_approval_percents":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":10},"tool_rejection_behaviors":{},"provision_source":"manual","tool_count":2}],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"max_turns":50,"active":false,"created":"2026-06-12T09:30:00Z","modified":"2026-06-12T09:30:00Z"},{"id":"019df7a2-44a0-7d66-b496-52c6c197bca1","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","description":"Triages inbound client support emails and drafts a reply.","instruction":"You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message, run the Customer Support Analyzer to classify the sender's sentiment and issue category, then draft a reply that directly answers what they asked in a warm but professional tone. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[{"id":"019df7a2-44a0-7ee9-8876-25aa7a902f38","task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":false,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"},{"id":"019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb","task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","revision_strategy":"pinned","task_name":"Draft Support Reply","order":1,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"}],"integrations":[],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"max_turns":50,"active":true,"created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z"}],"task_agent_run_visibility":"editors_and_owners","shared_with_project":true,"is_deleted":false,"created":"2026-05-05T10:15:00Z","modified":"2026-06-12T09:30:00Z"}}}}},"headers":{"X-New-Revision-ID":{"description":"ID of newly created TaskAgent revision, when the update created one","schema":{"type":"string","format":"uuid"},"example":"019df849-e12a-b57e-62d4-0e5875e91ef4"},"X-New-Revision-created":{"description":"Whether a new TaskAgent revision was created","schema":{"type":"string","enum":["true","false"]},"example":"true"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid configuration"}}},"description":"Bad Request - Invalid configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatetaskagent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent or referenced attachment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent_or_referenced_attachment [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent_or_referenced_attachment","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to update Task Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"delete":{"tags":["Task Agents"],"summary":"Delete Task Agent","description":"Remove a Task Agent from the project.\n\nThis will:\n- Remove the agent and its revision configuration\n- Preserve run history for auditing\n\nThis action cannot be undone.","operationId":"deleteTaskAgent","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Agent Id"},"description":"The specific Task Agent to reference."}],"responses":{"204":{"description":"Task Agent deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletetaskagent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to delete Task Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/revision":{"get":{"tags":["Task Agents"],"summary":"List Task Agent Revisions","operationId":"listTaskAgentRevisions","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"}],"responses":{"200":{"description":"Task Agent revisions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskAgentRevisionRead"},"title":"Response Listtaskagentrevisions"},"example":[{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","description":"Triages inbound client support emails, looks up the client's account, and drafts a reply.","instruction":"You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message: (1) run the Customer Support Analyzer to classify the sender's sentiment and issue category, (2) look up the client's account in the Customer Database sheet using their email address to confirm their plan, billing status, and any existing notes before you say anything about their account, (3) draft a reply that directly answers what they asked, references specific figures from the account lookup rather than the analyzer's summary, and matches a warm but professional tone, and (4) once a team member confirms the reply, log a one-line resolution note back to the Tickets sheet so the team can see the case was handled. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day. If the account lookup returns no match for the sender's email, say so plainly in the draft and ask the client to confirm the email address on file rather than guessing.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[{"id":"019df7a2-44a0-7ee9-8876-25aa7a902f38","task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":false,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"},{"id":"019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb","task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","revision_strategy":"pinned","task_name":"Draft Support Reply","order":1,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"}],"integrations":[{"id":"019ebb2a-b9c0-7af9-b42d-e9cd2819667d","project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_type":"google_sheets","integration_name":"Customer Database","order":0,"enabled":true,"credential_policy":"project_default","allowed_tool_ids":["019df7a2-44a0-7b09-afd0-c59cbc20126d","019df7a2-44a0-7923-9ea9-87be4ba93be9"],"default_action_mode":"auto_run","default_approval_percent":100,"default_rejection_behavior":"end_run","tool_action_modes":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":"require_approval"},"tool_approval_percents":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":10},"tool_rejection_behaviors":{},"provision_source":"manual","tool_count":2}],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"max_turns":50,"active":true,"created":"2026-06-12T09:30:00Z","modified":"2026-06-12T09:30:00Z"},{"id":"019df7a2-44a0-7d66-b496-52c6c197bca1","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","description":"Triages inbound client support emails and drafts a reply.","instruction":"You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message, run the Customer Support Analyzer to classify the sender's sentiment and issue category, then draft a reply that directly answers what they asked in a warm but professional tone. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[{"id":"019df7a2-44a0-7ee9-8876-25aa7a902f38","task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":false,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"},{"id":"019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb","task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","revision_strategy":"pinned","task_name":"Draft Support Reply","order":1,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"}],"integrations":[],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"max_turns":50,"active":false,"created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z"}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskagentrevisions"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to list Task Agent revisions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List immutable executable revisions for a Task Agent.\n\nEach revision contains the runtime configuration and pinned attachments that can\nbe executed by new runs, long-lived sessions, or pinned triggers. The active\nrevision is marked with `active`. Revisions are returned newest first."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/revision/{revision_id}":{"get":{"tags":["Task Agents"],"summary":"Get Task Agent Revision","operationId":"getTaskAgentRevision","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"revision_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Revision Id"}}],"responses":{"200":{"description":"Task Agent revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentRevisionRead"},"example":{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","description":"Triages inbound client support emails, looks up the client's account, and drafts a reply.","instruction":"You triage inbound client support emails for Fenwick & Co Bookkeeping. For every message: (1) run the Customer Support Analyzer to classify the sender's sentiment and issue category, (2) look up the client's account in the Customer Database sheet using their email address to confirm their plan, billing status, and any existing notes before you say anything about their account, (3) draft a reply that directly answers what they asked, references specific figures from the account lookup rather than the analyzer's summary, and matches a warm but professional tone, and (4) once a team member confirms the reply, log a one-line resolution note back to the Tickets sheet so the team can see the case was handled. Never promise a refund or credit yourself — say that a member of the team will confirm and action it within one business day. If the account lookup returns no match for the sender's email, say so plainly in the draft and ask the client to confirm the email address on file rather than guessing.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","llm_model_comments":[]},"task_tools":[{"id":"019df7a2-44a0-7ee9-8876-25aa7a902f38","task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":false,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"},{"id":"019ebb2a-b9c0-7d29-a460-f6aa6fd9edbb","task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","revision_strategy":"pinned","task_name":"Draft Support Reply","order":1,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","approval_percent":100,"rejection_behavior":"end_run"}],"integrations":[{"id":"019ebb2a-b9c0-7af9-b42d-e9cd2819667d","project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_type":"google_sheets","integration_name":"Customer Database","order":0,"enabled":true,"credential_policy":"project_default","allowed_tool_ids":["019df7a2-44a0-7b09-afd0-c59cbc20126d","019df7a2-44a0-7923-9ea9-87be4ba93be9"],"default_action_mode":"auto_run","default_approval_percent":100,"default_rejection_behavior":"end_run","tool_action_modes":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":"require_approval"},"tool_approval_percents":{"019df7a2-44a0-7923-9ea9-87be4ba93be9":10},"tool_rejection_behaviors":{},"provision_source":"manual","tool_count":2}],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"max_turns":50,"active":true,"created":"2026-06-12T09:30:00Z","modified":"2026-06-12T09:30:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentrevision"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent revision not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent_revision [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent_revision","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agent revision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve an immutable executable revision for a Task Agent.\n\nThe response includes the runtime configuration and concrete pinned attachments\nstored on that revision."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/token_report":{"get":{"tags":["Task Agents"],"summary":"Fetch Task Agent Token Report","description":"Retrieve aggregate reasoning token usage for a specific Task Agent.\n\nThis report includes:\n- Total input tokens across all agent runs\n- Total output tokens across all agent runs\n- Combined reasoning token usage\n- Number of runs included in the report\n\nFilters:\n- `start_date`: Include runs created on or after this date\n- `end_date`: Include runs created on or before this date\n\nDate parameters support both absolute and relative formats such as:\n- `2024-01-15`\n- `now`\n- `24 hours ago`\n- `yesterday`","operationId":"getTaskAgentTokenReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"description":"Start date for the report (e.g., '2023-06-01', '24 hours ago', 'yesterday')."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"description":"End date for the report (e.g., '2023-06-30', 'now', 'today')."}],"responses":{"200":{"description":"Task Agent token report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentTokenReport"},"example":{"task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","date_range":{"start":"2026-07-20T00:00:00Z","end":"2026-07-27T00:00:00Z"},"total_input_tokens":2800,"total_output_tokens":590,"total_tokens":3390,"total_runs":2}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid date range"}}},"description":"Bad Request - Invalid date range\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagenttokenreport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agent token report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/credit_report":{"get":{"tags":["Task Agents"],"summary":"Fetch Task Agent Credit Report","description":"Retrieve aggregate credit usage for a specific Task Agent.\n\nThis report includes:\n- Total credits charged across all Task Agent runs\n- Number of runs included in the report\n\nFilters:\n- `start_date`: Include runs created on or after this date\n- `end_date`: Include runs created on or before this date\n\nCredit reports are limited to a maximum 3-month lookback window. If `start_date`\nis omitted, the report defaults to the earliest permitted date.","operationId":"getTaskAgentCreditReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"description":"Start date for the report (e.g., '2023-06-01', '24 hours ago', 'yesterday')."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"description":"End date for the report (e.g., '2023-06-30', 'now', 'today')."}],"responses":{"200":{"description":"Task Agent credit report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentCreditReport"},"example":{"task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","date_range":{"start":"2026-07-20T00:00:00Z","end":"2026-07-27T00:00:00Z"},"total_credits":"6.15","total_runs":2}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid date range"}}},"description":"Bad Request - Invalid date range\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentcreditreport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agent credit report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/timing_report":{"get":{"tags":["Task Agents"],"summary":"Fetch Task Agent Timing Report","description":"Retrieve timing metrics for Task Agent executions.\n\nThis report includes:\n- Average Task Agent run duration\n- Aggregated timing metrics by hour or day\n- Completed run counts for each time bucket\n\nDefaults:\n- `aggregation=hour` returns the last 24 hours when no date range is provided\n- `aggregation=day` returns the last 7 days when no date range is provided","operationId":"getTaskAgentTimingReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"description":"Start date for the report (e.g., '2023-06-01', '24 hours ago', 'yesterday')."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"description":"End date for the report (e.g., '2023-06-30', 'now', 'today')."},{"name":"aggregation","in":"query","required":false,"schema":{"enum":["hour","day"],"type":"string","default":"hour","title":"Aggregation"},"description":"The aggregation level for the report. Can be either 'hour' or 'day'"}],"responses":{"200":{"description":"Task Agent timing report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentTimingReport"},"example":{"task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","date_range":{"start":"2026-07-26T09:00:00Z","end":"2026-07-27T09:00:00Z"},"aggregation":"hour","data":{"2026-07-27T09:00:00":{"avg_duration_ms":5515,"total_runs":2}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid date format or range"}}},"description":"Bad Request - Invalid date format or range\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagenttimingreport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agent timing report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/usage_report":{"get":{"tags":["Task Agents"],"summary":"Fetch Task Agent Usage Report","description":"Retrieve Task Agent run counts over time.\n\nThis report includes:\n- Run counts grouped by time bucket\n- Optional filtering to error runs only\n- Total run count across the reporting window\n\nDefaults:\n- `aggregation=day` returns the last 24 hours in hourly buckets\n- `aggregation=week` returns the last 7 days in daily buckets","operationId":"getTaskAgentUsageReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"aggregation","in":"query","required":false,"schema":{"enum":["day","week"],"type":"string","default":"day","title":"Aggregation"},"description":"The aggregation level for the report. Can be either 'day' or 'week'."},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UsageReportStatus","default":"ALL"},"description":"Run outcome filter for the report. Can be ALL, SUCCESS, or FAIL."},{"name":"errors_only","in":"query","required":false,"description":"If true, only include runs with errors in the report","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Task Agent usage report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentUsageReport"},"example":{"task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","date_range":{"start":"2026-07-20T00:00:00Z","end":"2026-07-27T00:00:00Z"},"aggregation":"day","status":"ALL","data":{"2026-07-20T00:00:00":1,"2026-07-27T00:00:00":2},"total_runs":3}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid aggregation parameter"}}},"description":"Bad Request - Invalid aggregation parameter\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentusagereport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agent usage report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/run":{"post":{"tags":["Task Agents"],"summary":"Run Task Agent","description":"Execute the Task Agent with a user message.\n\nThe agent will:\n1. Process the message using the configured LLM\n2. Reason about which task tools to invoke\n3. Execute relevant Tasks as needed\n4. Return a streaming response\n\nSend `application/json` for text, correlation fields, and optional base64-encoded\nfiles. Send `multipart/form-data` to upload binary files directly. Both formats\nrequire `message`.\n\nResponses are streamed using Server-Sent Events (SSE).\n\nThe first SSE event emitted after successful stream setup is:\n- `event_type: \"session_id\"` with the resolved `session_id` in `metadata`\n\nUse `revision_id` to execute a specific TaskAgent revision. New sessions can run\nany revision belonging to the TaskAgent. Existing sessions remain pinned to their\noriginal revision; passing a conflicting `revision_id` is rejected.\n\nSubsequent events include tool calls/results, text responses, metadata-only\n`memory_compaction` events when compaction memory runs, and the terminal `done`\nor `error` event. Compaction metadata may include token-threshold configuration\nsuch as `trigger: \"auto\"`, `token_threshold`, and `event_retention_size` when\ntoken-aware compaction is active.\n\nIf the model proposes a tool call gated behind `require_approval`, the stream\nends early with an `event_type: \"approval_required\"` event instead of a\nterminal `done`/`error` event. Its `metadata` carries `approval_request_id`,\n`tool_type`, `tool_name`, `tool_args_preview`, optional `agent_reason`, and\n`expires_at`; the run's status becomes `waiting_for_human` and stays paused\nuntil a human approves or rejects the request (see the approval-request\nendpoints) and a caller invokes the resume endpoint. Treat `agent_reason` as\nplain untrusted model-authored text.\n\nExample stream for a normal run — the agent classifies the message, looks up\nthe account in a connected integration, drafts a reply with a Task tool marked\nas the output formatter, and completes:\n\n```\ndata: {\"event_type\": \"session_id\", \"metadata\": {\"session_id\": \"...\"}, ...}\n\ndata: {\"event_type\": \"tool_call\", \"tool_name\": \"customer_support_analyzer\", \"tool_args\": {\"message\": \"...\"}, ...}\n\ndata: {\"event_type\": \"tool_result\", \"tool_name\": \"customer_support_analyzer\", \"tool_result\": {\"result\": {\"sentiment\": \"concerned\", ...}, \"task_run_id\": \"...\"}, \"tool_outcome\": \"success\", ...}\n\ndata: {\"event_type\": \"tool_call\", \"tool_name\": \"sheets_spreadsheets_values_get\", \"tool_args\": {\"spreadsheet_id\": \"...\", \"range\": \"Customers!A2:F500\"}, ...}\n\ndata: {\"event_type\": \"tool_result\", \"tool_name\": \"sheets_spreadsheets_values_get\", \"tool_result\": {\"range\": \"Customers!A2:F2\", \"values\": [[...]]}, \"tool_outcome\": \"success\", ...}\n\ndata: {\"event_type\": \"tool_call\", \"tool_name\": \"draft_support_reply\", \"tool_args\": {\"ticket_summary\": \"...\", \"customer_record\": {...}}, ...}\n\ndata: {\"event_type\": \"formatted_output\", \"content\": \"Hi Dana, ...\", \"tool_outcome\": \"success\", \"metadata\": {\"is_formatter_output\": true, \"task_run_id\": \"...\"}, ...}\n\ndata: {\"event_type\": \"done\", \"metadata\": {\"run_id\": \"...\", \"session_id\": \"...\", \"duration_ms\": 9130, \"total_tokens\": 2250, \"used_fallback_model\": false, \"fallback_model_id\": null}, ...}\n```\n\nTerminal `done` and `error` SSE events include fallback metadata when a run is\nknown: `used_fallback_model` and `fallback_model_id`. Terminal `error` events\nalso include stable `error_code` and `termination_reason` values. Current error\ncodes are `CONTEXT_WINDOW_EXCEEDED`, `INTEGRATION_NOT_CONNECTED`,\n`INTEGRATION_REAUTH_REQUIRED`, `INTEGRATION_AUTH_REQUIRED`,\n`UNSUPPORTED_INTEGRATION_TYPE`, `INSUFFICIENT_CREDITS`,\n`APPROVAL_CAPTURE_FAILED`, `FORMATTER_FAILED`, `FORMATTER_EMPTY_OUTPUT`,\n`TASK_AGENT_NOT_FOUND`, and `EXECUTION_ERROR`.","operationId":"runTaskAgent","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:run"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Agent Id"},"description":"The specific Task Agent to reference."},{"name":"revision_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Revision Id"},"description":"Optional TaskAgent revision ID to use for execution. If omitted, new sessions use the active revision and continuations use the session's pinned revision."}],"responses":{"200":{"description":"Streaming response","content":{"application/json":{"schema":{}},"text/event-stream":{"schema":{"type":"string"},"examples":{"normal_completion":{"summary":"Auto-run tools only: classify, look up the account, draft the reply, done","value":"data: {\"event_type\": \"session_id\", \"content\": null, \"tool_name\": null, \"tool_args\": null, \"tool_result\": null, \"tool_call_id\": null, \"tool_display_name\": null, \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {\"session_id\": \"019fa2da-4790-7718-8edc-ae551b239242\"}}\n\ndata: {\"event_type\": \"tool_call\", \"content\": null, \"tool_name\": \"customer_support_analyzer\", \"tool_args\": {\"message\": \"Subject: Charged twice for June invoice\\n\\nHi, I think we've been billed twice for our June bookkeeping retainer \\u2014 I can see two charges of \\u00a3450 on the 3rd and the 5th. Could someone check our account and let me know what's going on? Our account email is dana@northfieldjoinery.co.uk.\\n\\nThanks,\\nDana\"}, \"tool_result\": null, \"tool_call_id\": \"call-1a2b3c4d5e6f\", \"tool_display_name\": \"Customer Support Analyzer\", \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {}}\n\ndata: {\"event_type\": \"tool_result\", \"content\": null, \"tool_name\": \"customer_support_analyzer\", \"tool_args\": null, \"tool_result\": {\"result\": {\"sentiment\": \"concerned\", \"category\": \"billing_dispute\", \"suggested_response\": \"Confirm the duplicate charge, check the account, and let the customer know a refund will be reviewed.\"}, \"task_run_id\": \"019fa2da-4790-798a-9530-76940e914d17\"}, \"tool_call_id\": \"call-1a2b3c4d5e6f\", \"tool_display_name\": \"Customer Support Analyzer\", \"tool_outcome\": \"success\", \"presentation\": null, \"error\": null, \"metadata\": {}}\n\ndata: {\"event_type\": \"tool_call\", \"content\": null, \"tool_name\": \"sheets_spreadsheets_values_get\", \"tool_args\": {\"spreadsheet_id\": \"1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms\", \"range\": \"Customers!A2:F500\"}, \"tool_result\": null, \"tool_call_id\": \"call-2b3c4d5e6f70\", \"tool_display_name\": \"Customer Database\", \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {}}\n\ndata: {\"event_type\": \"tool_result\", \"content\": null, \"tool_name\": \"sheets_spreadsheets_values_get\", \"tool_args\": null, \"tool_result\": {\"range\": \"Customers!A2:F2\", \"majorDimension\": \"ROWS\", \"values\": [[\"NJ-1042\", \"Dana Whitfield\", \"dana@northfieldjoinery.co.uk\", \"Bookkeeping Retainer - Standard\", \"active\", \"No prior disputes\"]]}, \"tool_call_id\": \"call-2b3c4d5e6f70\", \"tool_display_name\": \"Customer Database\", \"tool_outcome\": \"success\", \"presentation\": null, \"error\": null, \"metadata\": {}}\n\ndata: {\"event_type\": \"tool_call\", \"content\": null, \"tool_name\": \"draft_support_reply\", \"tool_args\": {\"ticket_summary\": \"Customer reports being charged twice for the June retainer (\\u00a3450 x2 on 3 and 5 July).\", \"customer_record\": {\"account_id\": \"NJ-1042\", \"name\": \"Dana Whitfield\", \"plan\": \"Bookkeeping Retainer - Standard\", \"status\": \"active\"}}, \"tool_result\": null, \"tool_call_id\": \"call-3c4d5e6f7081\", \"tool_display_name\": \"Draft Support Reply\", \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {}}\n\ndata: {\"event_type\": \"formatted_output\", \"content\": \"Hi Dana,\\n\\nThanks for flagging this \\u2014 I can see two \\u00a3450 charges against your Bookkeeping Retainer account (NJ-1042) on 3 and 5 July, and that does look like a duplicate. There are no other disputes on file, so this should be straightforward.\\n\\nI can't issue the refund myself, but I've flagged it to the team and someone will confirm and process it within one business day.\\n\\nThanks for your patience,\\nSupport Triage\", \"tool_name\": \"draft_support_reply\", \"tool_args\": null, \"tool_result\": null, \"tool_call_id\": \"call-3c4d5e6f7081\", \"tool_display_name\": \"Draft Support Reply\", \"tool_outcome\": \"success\", \"presentation\": null, \"error\": null, \"metadata\": {\"is_formatter_output\": true, \"task_run_id\": \"019fa2da-4790-7bff-bc7a-c397d193f25e\"}}\n\ndata: {\"event_type\": \"done\", \"content\": null, \"tool_name\": null, \"tool_args\": null, \"tool_result\": null, \"tool_call_id\": null, \"tool_display_name\": null, \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {\"run_id\": \"019fa2da-4790-712c-aaa2-cb8d287b620b\", \"session_id\": \"019fa2da-4790-7718-8edc-ae551b239242\", \"duration_ms\": 9130, \"total_tokens\": 2250, \"used_fallback_model\": false, \"fallback_model_id\": null}}\n\n"},"approval_required":{"summary":"Stream ends early because the next tool call requires human approval","value":"data: {\"event_type\": \"session_id\", \"content\": null, \"tool_name\": null, \"tool_args\": null, \"tool_result\": null, \"tool_call_id\": null, \"tool_display_name\": null, \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {\"session_id\": \"019fa2da-4790-7718-8edc-ae551b239242\"}}\n\ndata: {\"event_type\": \"approval_required\", \"content\": \"Approval required before executing tool.\", \"tool_name\": null, \"tool_args\": null, \"tool_result\": null, \"tool_call_id\": \"call-4f19a7c3e8b2\", \"tool_display_name\": null, \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {\"run_id\": \"019fa2e2-2f00-7be2-bcf0-f056f44f700a\", \"session_id\": \"019fa2da-4790-7718-8edc-ae551b239242\", \"approval_request_id\": \"019fa2e2-2f00-71c7-aee7-539ab31cd302\", \"task_agent_id\": \"019df849-e106-3301-5894-291b4c9c6cab\", \"task_agent_revision_id\": \"019df849-e12a-b57e-62d4-0e5875e91ef4\", \"tool_type\": \"integration\", \"tool_name\": \"sheets_spreadsheets_values_append\", \"tool_args_preview\": {\"spreadsheet_id\": \"1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms\", \"range\": \"Tickets!A:D\", \"value_input_option\": \"USER_ENTERED\", \"values\": [[\"NJ-1042\", \"TCK-4821\", \"resolved\", \"2026-07-27\"]]}, \"agent_reason\": \"The resolved support ticket must be recorded for follow-up.\", \"reason\": \"This tool requires approval before execution.\", \"expires_at\": \"2026-07-27T10:22:41Z\"}}\n\n"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid request"}}},"description":"Bad Request - Invalid request\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Runtaskagent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have run permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"run"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to run Task Agent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"requestBody":{"required":true,"content":{"application/json":{"x-fern-sdk-method-name":"runTaskAgent","schema":{"type":"object","properties":{"message":{"type":"string","description":"User message to send to the agent."},"session_id":{"type":["string","null"],"description":"Server-generated session ID from an earlier run. Omit to start a new session."},"reference":{"type":["string","null"],"maxLength":64,"description":"Optional reference for external correlation."},"context_id":{"anyOf":[{"type":"string","maxLength":64,"not":{"pattern":"^eval:"}},{"type":"null"}],"description":"Optional context ID for grouping runs. The `eval:` prefix is reserved."},"files":{"type":["array","null"],"description":"Optional base64-encoded files.","items":{"type":"object","properties":{"content":{"type":"string","format":"byte","description":"Base64-encoded file content."},"filename":{"type":"string","description":"Original filename. The server generates one when omitted."}},"required":["content"]}},"chaos":{"anyOf":[{"allOf":[{"$ref":"#/components/schemas/TaskAgentChaosConfig"},{"if":{"properties":{"enabled":{"const":false}},"required":["enabled"]},"else":{"properties":{"modes":{"minItems":1}},"required":["modes"]}}]},{"type":"null"}],"description":"Optional bounded run-scoped chaos policy."}},"required":["message"]},"examples":{"normal_completion":{"summary":"Auto-run tools only: classify, look up the account, draft the reply, done","value":{"message":"Subject: Charged twice for June invoice\n\nHi, I think we've been billed twice for our June bookkeeping retainer — I can see two charges of £450 on the 3rd and the 5th. Could someone check our account and let me know what's going on? Our account email is dana@northfieldjoinery.co.uk.\n\nThanks,\nDana"}},"approval_required":{"summary":"Stream ends early because the next tool call requires human approval","value":{"message":"Refund the duplicate charge on invoice INV-1042."}}}},"multipart/form-data":{"x-fern-sdk-method-name":"runTaskAgentMultipart","schema":{"type":"object","properties":{"message":{"type":"string","description":"User message to send to the agent.","minLength":1},"session_id":{"type":["string","null"],"description":"Server-generated session ID from an earlier run. Omit to start a new session."},"reference":{"type":["string","null"],"maxLength":64,"description":"Optional reference for external correlation."},"context_id":{"anyOf":[{"type":"string","maxLength":64,"not":{"pattern":"^eval:"}},{"type":"null"}],"description":"Optional context ID for grouping runs. The `eval:` prefix is reserved."},"files":{"type":"array","description":"Optional binary files.","items":{"type":"string","format":"binary"}},"chaos":{"type":"string","contentMediaType":"application/json","contentSchema":{"allOf":[{"$ref":"#/components/schemas/TaskAgentChaosConfig"},{"if":{"properties":{"enabled":{"const":false}},"required":["enabled"]},"else":{"properties":{"modes":{"minItems":1}},"required":["modes"]}}]},"description":"Optional JSON-encoded bounded run-scoped chaos policy."}},"required":["message"]}}}}},"get":{"tags":["Task Agents"],"summary":"List Task Agent Runs","description":"List execution runs for a Task Agent.\n\nReturns run history with:\n- Input message\n- Token usage\n- Status and duration\n- Actor and execution entry-point information\n- Trigger type (`manual`, `api`, `slack`, or a trigger type such as `schedule`,\n  `webhook`, or `gmail_inbox`)\n- Task tools invoked\n- MCP tools invoked\n- Phase timings for LLM, tool execution, and memory compaction when applicable","operationId":"listTaskAgentRuns","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"session_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"description":"Filter by session ID"},{"name":"is_error","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Error"},"description":"Filter by run-level error status."},{"name":"had_task_tool_fail","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Had Task Tool Fail"},"description":"Filter by whether any invoked task tool failed."},{"name":"had_mcp_tool_fail","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Had Mcp Tool Fail"},"description":"Filter by whether any invoked MCP tool failed."},{"name":"had_integration_tool_fail","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Had Integration Tool Fail"},"description":"Filter by whether any invoked integration tool failed."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentRunStatus"},{"type":"null"}],"title":"Status"},"description":"Filter by run status."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created After"},"description":"Filter runs created at/after this timestamp."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Before"},"description":"Filter runs created at/before this timestamp."},{"name":"min_duration_ms","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"Min Duration Ms"},"description":"Filter runs with duration greater than or equal to this value."},{"name":"task_agent_revision_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"},"description":"Filter by TaskAgent revision ID."},{"name":"trigger_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger Type"},"description":"Filter by how the run was triggered. Non-trigger sources include manual, api, and slack; trigger executions use their trigger type value such as schedule, webhook, or gmail_inbox."},{"name":"chaos_enabled","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Chaos Enabled"},"description":"Filter by whether the run has a chaos policy."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"Run history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskAgentRunRead_"},"example":{"results":[{"id":"019fa2e2-2f00-7be2-bcf0-f056f44f700a","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","user_id":"0190c234-1111-2222-3333-444444444444","actor_user_id":"0190c234-1111-2222-3333-444444444444","actor_basis":"direct_user","execution_surface":"task_agent_approval_resume","execution_source_id":"019fa2e2-2f00-71c7-aee7-539ab31cd302","invocation_id":"019fa2e2-2f00-7a54-9f70-cd49ad3571d2","invocation_ids":["019fa2e2-2f00-7a54-9f70-cd49ad3571d2"],"is_continuation":true,"primary_llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","used_fallback_model":false,"input_tokens":960,"output_tokens":180,"total_tokens":1140,"charged_credits":"2.05","total_charged_credits":"2.05","created":"2026-07-27T09:22:40Z","completed":"2026-07-27T09:24:20Z","duration_ms":100000,"status":"completed","is_error":false,"approval_request_ids":["019fa2e2-2f00-71c7-aee7-539ab31cd302"],"approval_requests":[{"id":"019fa2e2-2f00-71c7-aee7-539ab31cd302","status":"approved","tool_type":"integration","tool_name":"sheets_spreadsheets_values_append","requested_at":"2026-07-27T09:22:41Z","decided_at":"2026-07-27T09:24:15Z","requested_by_user_id":"0190c234-1111-2222-3333-444444444444","decided_by_user_id":"019df7a2-44a0-7f54-8478-e19c351d1cc8","decision_note":"Approved — logging the resolved ticket is fine."}],"had_task_tool_fail":false,"had_mcp_tool_fail":false,"had_integration_tool_fail":false,"task_tools_invoked":[{"task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","task_name":"Draft Support Reply","task_run_id":"019fa2e2-2f00-7f38-a32e-85d18e953d52","is_error":false,"is_formatter":true,"duration_ms":1360}],"integration_tools_invoked":[{"integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_name":"Customer Database","integration_type":"google_sheets","integration_tool_id":"019df7a2-44a0-7923-9ea9-87be4ba93be9","tool_name":"sheets_spreadsheets_values_append","principal_type":"project_default","is_error":false,"duration_ms":510}],"last_activity_at":"2026-07-27T09:24:20Z","trigger_type":"api","model_usages":[{"id":"019fa2e2-2f00-76c3-8b69-2a582554fe03","task_agent_run_id":"019fa2e2-2f00-7be2-bcf0-f056f44f700a","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","usage_scope":"reasoning","usage_type":"primary","input_tokens":960,"output_tokens":180,"total_tokens":1140,"charged_credits":"2.05","call_count":2,"created":"2026-07-27T09:22:40Z","modified":"2026-07-27T09:24:20Z"}],"files":[],"is_chaos_run":false},{"id":"019fa2da-4790-712c-aaa2-cb8d287b620b","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","user_id":"0190c234-1111-2222-3333-444444444444","actor_user_id":"0190c234-1111-2222-3333-444444444444","actor_basis":"direct_user","execution_surface":"task_agent_api","execution_source_id":"019df849-e106-3301-5894-291b4c9c6cab","invocation_id":"019fa2da-4790-7e73-b7af-bfd124a96ed6","invocation_ids":["019fa2da-4790-7e73-b7af-bfd124a96ed6"],"is_continuation":false,"primary_llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","used_fallback_model":false,"input_tokens":1840,"output_tokens":410,"total_tokens":2250,"charged_credits":"4.10","total_charged_credits":"4.10","created":"2026-07-27T09:14:02Z","completed":"2026-07-27T09:14:11Z","duration_ms":9130,"status":"completed","is_error":false,"approval_request_ids":[],"approval_requests":[],"had_task_tool_fail":false,"had_mcp_tool_fail":false,"had_integration_tool_fail":false,"task_tools_invoked":[{"task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","task_name":"Customer Support Analyzer","task_run_id":"019fa2da-4790-798a-9530-76940e914d17","is_error":false,"is_formatter":false,"duration_ms":1120},{"task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","task_name":"Draft Support Reply","task_run_id":"019fa2da-4790-7bff-bc7a-c397d193f25e","is_error":false,"is_formatter":true,"duration_ms":2380}],"integration_tools_invoked":[{"integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_name":"Customer Database","integration_type":"google_sheets","integration_tool_id":"019df7a2-44a0-7b09-afd0-c59cbc20126d","tool_name":"sheets_spreadsheets_values_get","principal_type":"project_default","is_error":false,"duration_ms":640}],"phase_timings":[{"phase":"llm_inference","start_ms":0,"end_ms":1450},{"phase":"integration_tool_execution","start_ms":1450,"end_ms":2090,"call_id":"call-2b3c4d5e6f70","tool_name":"sheets_spreadsheets_values_get","integration_name":"Customer Database"},{"phase":"task_tool_execution","start_ms":2090,"end_ms":4470,"call_id":"call-3c4d5e6f7081","task_run_id":"019fa2da-4790-7bff-bc7a-c397d193f25e"}],"context_usage":{"schema_version":1,"estimator_version":"task_agent_context_usage_v1","input_tokens":{"provider_total":1840,"observed_provider_total":1840,"estimated_total":1890,"uncategorized":0,"breakdown":{"skills":0,"mcp_tools":0,"task_tools":20,"input_files":0,"instructions":153,"integrations":0,"runtime_file":108,"registered_tools":0,"conversation_history":0,"current_user_message":23}},"input_files":{"estimated_tokens":0,"file_count":0,"text_file_count":0,"binary_file_count":0,"total_bytes":0},"output_tokens":{"provider_total":410,"observed_provider_total":410},"runtime_components":{"skills":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"loaded_payloads":0,"provenance":{}},"mcp_tools":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"provenance":{}},"task_tools":{"estimated_tokens":20,"tool_declarations":{"estimated_tokens":20,"count":1,"unavailable_count":0,"error_count":0},"provenance":{"manual":20}},"integrations":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"provenance":{}},"runtime_file":{"estimated_tokens":108,"tool_declarations":{"estimated_tokens":108,"count":1,"unavailable_count":0,"error_count":0},"provenance":{"manual":108}},"registered_tools":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"provenance":{}}},"metadata":{"request_count":1,"partial":false,"provider_usage_missing":false,"provider_usage_complete":true,"observed_provider_total_tokens":2250,"estimation_truncated":false,"truncated_estimate_count":0,"estimation_methods":["utf8_bytes_div_4"]}},"last_activity_at":"2026-07-27T09:14:11Z","trigger_type":"api","model_usages":[{"id":"019fa2da-4790-7fa0-9552-00540687d1cb","task_agent_run_id":"019fa2da-4790-712c-aaa2-cb8d287b620b","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","usage_scope":"reasoning","usage_type":"primary","input_tokens":1840,"output_tokens":410,"total_tokens":2250,"charged_credits":"4.10","call_count":3,"created":"2026-07-27T09:14:02Z","modified":"2026-07-27T09:14:11Z"}],"files":[],"is_chaos_run":false}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskagentruns"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to list runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/approval-request":{"get":{"tags":["Task Agents"],"summary":"List Task Agent Approval Requests","operationId":"listTaskAgentApprovalRequests","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentApprovalRequestStatus"},{"type":"null"}],"title":"Status"},"description":"Filter by approval request status."},{"name":"run_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Run Id"},"description":"Filter by TaskAgentRun ID."},{"name":"session_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"description":"Filter by ADK session ID."},{"name":"tool_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentToolSource"},{"type":"null"}],"title":"Tool Type"},"description":"Filter by tool source."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created After"},"description":"Filter approval requests created at/after this timestamp."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created Before"},"description":"Filter approval requests created at/before this timestamp."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"Task Agent approval requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskAgentApprovalRequestRead_"},"example":{"results":[{"id":"019fa2e2-2f00-71c7-aee7-539ab31cd302","project_id":"0190a234-9876-5432-10ab-cdef01234567","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_run_id":"019fa2e2-2f00-7be2-bcf0-f056f44f700a","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","invocation_id":"019fa2e2-2f00-7a54-9f70-cd49ad3571d2","function_call_id":"call-4f19a7c3e8b2","adk_event_id":"019fa2e2-2f00-77e0-a459-008f7d11e9f8","requested_by_user_id":"0190c234-1111-2222-3333-444444444444","requested_by_actor_type":"user","requester_is_decider":false,"tool_action_control_id":"019fa2e2-2f00-7d54-ab2e-0fd98d058991","action_mode_snapshot":"require_approval","tool_type":"integration","tool_name":"sheets_spreadsheets_values_append","tool_ref":{"project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_tool_id":"019df7a2-44a0-7923-9ea9-87be4ba93be9"},"tool_args_hash":"e3f1c9a7b2d4f6081a5c9e3d7b2f4a6081c5e9d3b7f2a4c6081e5d9c3b7f2a46","tool_args_preview":{"spreadsheet_id":"1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms","range":"Tickets!A:D","value_input_option":"USER_ENTERED","values":[["NJ-1042","TCK-4821","resolved","2026-07-27"]]},"agent_reason":"The resolved support ticket must be recorded for follow-up.","status":"pending","created":"2026-07-27T09:22:41Z","modified":"2026-07-27T09:22:41Z","expires_at":"2026-07-27T10:22:41Z"}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid approval request filters"}}},"description":"Bad Request - Invalid approval request filters\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskagentapprovalrequests"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to list Task Agent approval requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List human approval requests for proposed Task Agent tool calls.\n\nApproval requests are visible through the same visibility rules as their linked\nTask Agent run. Pending requests may be returned as expired when their approval\nwindow has elapsed."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/approval-request/{approval_request_id}":{"get":{"tags":["Task Agents"],"summary":"Get Task Agent Approval Request","operationId":"getTaskAgentApprovalRequest","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"approval_request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Approval Request Id"},"description":"The approval request ID"}],"responses":{"200":{"description":"Task Agent approval request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentApprovalRequestRead"},"example":{"id":"019fa2e2-2f00-71c7-aee7-539ab31cd302","project_id":"0190a234-9876-5432-10ab-cdef01234567","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_run_id":"019fa2e2-2f00-7be2-bcf0-f056f44f700a","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","invocation_id":"019fa2e2-2f00-7a54-9f70-cd49ad3571d2","function_call_id":"call-4f19a7c3e8b2","adk_event_id":"019fa2e2-2f00-77e0-a459-008f7d11e9f8","requested_by_user_id":"0190c234-1111-2222-3333-444444444444","requested_by_actor_type":"user","requester_is_decider":false,"tool_action_control_id":"019fa2e2-2f00-7d54-ab2e-0fd98d058991","action_mode_snapshot":"require_approval","tool_type":"integration","tool_name":"sheets_spreadsheets_values_append","tool_ref":{"project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_tool_id":"019df7a2-44a0-7923-9ea9-87be4ba93be9"},"tool_args_hash":"e3f1c9a7b2d4f6081a5c9e3d7b2f4a6081c5e9d3b7f2a4c6081e5d9c3b7f2a46","tool_args_preview":{"spreadsheet_id":"1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms","range":"Tickets!A:D","value_input_option":"USER_ENTERED","values":[["NJ-1042","TCK-4821","resolved","2026-07-27"]]},"agent_reason":"The resolved support ticket must be recorded for follow-up.","status":"pending","created":"2026-07-27T09:22:41Z","modified":"2026-07-27T09:22:41Z","expires_at":"2026-07-27T10:22:41Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentapprovalrequest"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Approval request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find approval_request [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"approval_request","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agent approval request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve a human approval request for a proposed tool call.\n\nThe request is visible only when the caller can read the linked Task Agent run.\nIf the request is pending and has expired, it is transitioned to expired before\nthe response is returned. `agent_reason`, when present, is plain untrusted text\nauthored by the model for this specific tool call."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/approval-request/{approval_request_id}/approve":{"post":{"tags":["Task Agents"],"summary":"Approve Task Agent Approval Request","operationId":"approveTaskAgentApprovalRequest","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:run"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"approval_request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Approval Request Id"},"description":"The approval request ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentApprovalRequestApprove"},"examples":{"empty":{"summary":"Approve with no note","value":{}},"with_note":{"summary":"Approve with a decision note","value":{"decision_note":"Checked the recipient list; safe to send."}}}}}},"responses":{"200":{"description":"Task Agent approval request approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentApprovalRequestRead"},"examples":{"Approve with no note":{"summary":"Approve with no note","value":{"id":"019fa2e2-2f00-71c7-aee7-539ab31cd302","project_id":"0190a234-9876-5432-10ab-cdef01234567","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_run_id":"019fa2e2-2f00-7be2-bcf0-f056f44f700a","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","invocation_id":"019fa2e2-2f00-7a54-9f70-cd49ad3571d2","function_call_id":"call-4f19a7c3e8b2","adk_event_id":"019fa2e2-2f00-77e0-a459-008f7d11e9f8","requested_by_user_id":"0190c234-1111-2222-3333-444444444444","requested_by_actor_type":"user","decided_by_user_id":"019df7a2-44a0-7f54-8478-e19c351d1cc8","requester_is_decider":false,"tool_action_control_id":"019fa2e2-2f00-7d54-ab2e-0fd98d058991","action_mode_snapshot":"require_approval","tool_type":"integration","tool_name":"sheets_spreadsheets_values_append","tool_ref":{"project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_tool_id":"019df7a2-44a0-7923-9ea9-87be4ba93be9"},"tool_args_hash":"e3f1c9a7b2d4f6081a5c9e3d7b2f4a6081c5e9d3b7f2a4c6081e5d9c3b7f2a46","tool_args_preview":{"spreadsheet_id":"1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms","range":"Tickets!A:D","value_input_option":"USER_ENTERED","values":[["NJ-1042","TCK-4821","resolved","2026-07-27"]]},"agent_reason":"The resolved support ticket must be recorded for follow-up.","status":"approved","decision":"approved","decision_note":"Approved — logging the resolved ticket is fine.","created":"2026-07-27T09:22:41Z","modified":"2026-07-27T09:24:15Z","decided_at":"2026-07-27T09:24:15Z","expires_at":"2026-07-27T10:22:41Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid approval decision"}}},"description":"Bad Request - Invalid approval decision\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Approvetaskagentapprovalrequest"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have run permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"run"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Approval request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find approval_request [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"approval_request","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"409":{"description":"Approval request is not pending"},"500":{"description":"Internal Server Error - Failed to approve Task Agent approval request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Approve a pending human approval request.\n\nApproving records the human decision and creates a bounded one-shot allowance\nfor the exact proposed tool call. Approval does not automatically execute the\nagent; callers must invoke the explicit resume endpoint to continue the paused\nrun."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/approval-request/{approval_request_id}/reject":{"post":{"tags":["Task Agents"],"summary":"Reject Task Agent Approval Request","operationId":"rejectTaskAgentApprovalRequest","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:run"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"approval_request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Approval Request Id"},"description":"The approval request ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentApprovalRequestReject"},"examples":{"with_note":{"summary":"Reject with a decision note","value":{"decision_note":"Recipient list includes external addresses."}}}}}},"responses":{"200":{"description":"Task Agent approval request rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentApprovalRequestRead"},"examples":{"Reject with a decision note":{"summary":"Reject with a decision note","value":{"id":"019fa2e2-2f00-71c7-aee7-539ab31cd302","project_id":"0190a234-9876-5432-10ab-cdef01234567","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_run_id":"019fa2e2-2f00-7be2-bcf0-f056f44f700a","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","invocation_id":"019fa2e2-2f00-7a54-9f70-cd49ad3571d2","function_call_id":"call-4f19a7c3e8b2","adk_event_id":"019fa2e2-2f00-77e0-a459-008f7d11e9f8","requested_by_user_id":"0190c234-1111-2222-3333-444444444444","requested_by_actor_type":"user","decided_by_user_id":"019df7a2-44a0-7f54-8478-e19c351d1cc8","requester_is_decider":false,"tool_action_control_id":"019fa2e2-2f00-7d54-ab2e-0fd98d058991","action_mode_snapshot":"require_approval","tool_type":"integration","tool_name":"sheets_spreadsheets_values_append","tool_ref":{"project_integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_tool_id":"019df7a2-44a0-7923-9ea9-87be4ba93be9"},"tool_args_hash":"e3f1c9a7b2d4f6081a5c9e3d7b2f4a6081c5e9d3b7f2a4c6081e5d9c3b7f2a46","tool_args_preview":{"spreadsheet_id":"1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms","range":"Tickets!A:D","value_input_option":"USER_ENTERED","values":[["NJ-1042","TCK-4821","resolved","2026-07-27"]]},"agent_reason":"The resolved support ticket must be recorded for follow-up.","status":"rejected","decision":"rejected","decision_note":"Don't log yet — waiting on the client to confirm the refund amount.","created":"2026-07-27T09:22:41Z","modified":"2026-07-27T09:24:15Z","decided_at":"2026-07-27T09:24:15Z","expires_at":"2026-07-27T10:22:41Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid approval decision"}}},"description":"Bad Request - Invalid approval decision\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Rejecttaskagentapprovalrequest"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have run permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"run"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Approval request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find approval_request [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"approval_request","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"409":{"description":"Approval request is not pending"},"500":{"description":"Internal Server Error - Failed to reject Task Agent approval request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Reject a pending human approval request.\n\nThe default rejection behavior fails the linked paused Task Agent run with an\napproval rejection termination reason. When the matched action control uses\n`return_rejection_to_model`, rejection records the decision and leaves the run\nwaiting until the explicit resume endpoint returns the controlled rejection\nfunction response to the model."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/approval-request/{approval_request_id}/resume":{"post":{"tags":["Task Agents"],"summary":"Resume Task Agent Approval Request","operationId":"resumeTaskAgentApprovalRequest","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:run"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"approval_request_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Approval Request Id"},"description":"The approval request ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentApprovalRequestResume"},"examples":{"empty":{"summary":"Resume with the internal continuation message","description":"Omit `message` to use the controlled internal approval-resume continuation message.","value":{}},"guarded":{"summary":"Resume, guarded to one run","description":"`task_agent_run_id` and `session_id` are optional guards: the resume only applies to that run.","value":{"task_agent_run_id":"019dda43-31e6-1f5f-1639-9b6cb322b9a1","message":"Approved by the on-call reviewer."}}}}}},"responses":{"200":{"description":"Streaming response","content":{"text/event-stream":{"schema":{"type":"string"},"examples":{"Resume with the internal continuation message":{"summary":"Resume with the internal continuation message","value":"data: {\"event_type\": \"session_id\", \"content\": null, \"tool_name\": null, \"tool_args\": null, \"tool_result\": null, \"tool_call_id\": null, \"tool_display_name\": null, \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {\"session_id\": \"019fa2da-4790-7718-8edc-ae551b239242\"}}\n\ndata: {\"event_type\": \"tool_result\", \"content\": null, \"tool_name\": \"sheets_spreadsheets_values_append\", \"tool_args\": null, \"tool_result\": {\"spreadsheetId\": \"1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms\", \"tableRange\": \"Tickets!A2:D2\", \"updates\": {\"updatedRange\": \"Tickets!A3:D3\", \"updatedRows\": 1, \"updatedColumns\": 4, \"updatedCells\": 4}}, \"tool_call_id\": \"call-4f19a7c3e8b2\", \"tool_display_name\": \"Customer Database\", \"tool_outcome\": \"success\", \"presentation\": null, \"error\": null, \"metadata\": {}}\n\ndata: {\"event_type\": \"tool_call\", \"content\": null, \"tool_name\": \"draft_support_reply\", \"tool_args\": {\"ticket_summary\": \"Confirm ticket TCK-4821 was logged as resolved.\", \"customer_record\": {\"account_id\": \"NJ-1042\", \"name\": \"Dana Whitfield\", \"plan\": \"Bookkeeping Retainer - Standard\", \"status\": \"active\"}}, \"tool_result\": null, \"tool_call_id\": \"call-5a6b7c8d9e0f\", \"tool_display_name\": \"Draft Support Reply\", \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {}}\n\ndata: {\"event_type\": \"formatted_output\", \"content\": \"Logged \\u2014 ticket TCK-4821 is marked resolved in the tracker.\", \"tool_name\": \"draft_support_reply\", \"tool_args\": null, \"tool_result\": null, \"tool_call_id\": \"call-5a6b7c8d9e0f\", \"tool_display_name\": \"Draft Support Reply\", \"tool_outcome\": \"success\", \"presentation\": null, \"error\": null, \"metadata\": {\"is_formatter_output\": true, \"task_run_id\": \"019fa2e2-2f00-7f38-a32e-85d18e953d52\"}}\n\ndata: {\"event_type\": \"done\", \"content\": null, \"tool_name\": null, \"tool_args\": null, \"tool_result\": null, \"tool_call_id\": null, \"tool_display_name\": null, \"tool_outcome\": null, \"presentation\": null, \"error\": null, \"metadata\": {\"run_id\": \"019fa2e2-2f00-7be2-bcf0-f056f44f700a\", \"session_id\": \"019fa2da-4790-7718-8edc-ae551b239242\", \"duration_ms\": 1870, \"total_tokens\": 1140, \"used_fallback_model\": false, \"fallback_model_id\": null}}\n\n"}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid approval resume"}}},"description":"Bad Request - Invalid approval resume\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Resumetaskagentapprovalrequest"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have run permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"run"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Approval request not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find approval_request [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"approval_request","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"409":{"description":"Approval request or linked run is not resumable"},"500":{"description":"Internal Server Error - Failed to resume Task Agent approval request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Resume a paused Task Agent run after an approval decision.\n\nResume reuses the original TaskAgentRun ID, ADK session ID, ADK session owner\nkey, and pinned TaskAgent revision. Approved requests allow the exact approved\ntool call once. Rejected requests are resumable only when the matched action\ncontrol uses `return_rejection_to_model`, in which case the service resumes ADK\nwith a controlled function response for the original function call.\n\nExample stream after an approval is granted: the approved tool executes and\nits `tool_result` is emitted directly (the proposing `tool_call` was already\nshown via the original run's `approval_required` event, so it is not repeated),\nfollowed by any further reasoning, the terminal `formatted_output`, and `done`:\n\n```\ndata: {\"event_type\": \"tool_result\", \"tool_name\": \"sheets_spreadsheets_values_append\", ...}\n\ndata: {\"event_type\": \"tool_call\", \"tool_name\": \"draft_support_reply\", ...}\n\ndata: {\"event_type\": \"formatted_output\", \"content\": \"Logged — ticket TCK-4821 is marked resolved in the tracker.\", ...}\n\ndata: {\"event_type\": \"done\", \"metadata\": {\"run_id\": \"...\", \"session_id\": \"...\", ...}}\n```\n\nTerminal `done` and `error` SSE events include fallback metadata when a run is\nknown: `used_fallback_model` and `fallback_model_id`. Terminal `error` events\nalso include stable `error_code` and `termination_reason` values. Current error\ncodes are `CONTEXT_WINDOW_EXCEEDED`, `INTEGRATION_NOT_CONNECTED`,\n`INTEGRATION_REAUTH_REQUIRED`, `INTEGRATION_AUTH_REQUIRED`,\n`UNSUPPORTED_INTEGRATION_TYPE`, `INSUFFICIENT_CREDITS`,\n`APPROVAL_CAPTURE_FAILED`, `FORMATTER_FAILED`, `FORMATTER_EMPTY_OUTPUT`,\n`TASK_AGENT_NOT_FOUND`, and `EXECUTION_ERROR`."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/run/{run_id}":{"get":{"tags":["Task Agents"],"summary":"Get Task Agent Run","description":"Get a single execution run for a Task Agent by run ID.\n\nReturns the same run metadata shape as the run listing endpoint, including\nstatus, token usage, files, tool invocation summaries, phase timings, fallback\nmetadata, model usage rows, and execution identity when available.","operationId":"getTaskAgentRun","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"},"description":"The task agent run ID"}],"responses":{"200":{"description":"Task Agent run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentRunRead"},"example":{"id":"019fa2da-4790-712c-aaa2-cb8d287b620b","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","user_id":"0190c234-1111-2222-3333-444444444444","actor_user_id":"0190c234-1111-2222-3333-444444444444","actor_basis":"direct_user","execution_surface":"task_agent_api","execution_source_id":"019df849-e106-3301-5894-291b4c9c6cab","invocation_id":"019fa2da-4790-7e73-b7af-bfd124a96ed6","invocation_ids":["019fa2da-4790-7e73-b7af-bfd124a96ed6"],"is_continuation":false,"primary_llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","used_fallback_model":false,"input_tokens":1840,"output_tokens":410,"total_tokens":2250,"charged_credits":"4.10","total_charged_credits":"4.10","created":"2026-07-27T09:14:02Z","completed":"2026-07-27T09:14:11Z","duration_ms":9130,"status":"completed","is_error":false,"approval_request_ids":[],"approval_requests":[],"had_task_tool_fail":false,"had_mcp_tool_fail":false,"had_integration_tool_fail":false,"task_tools_invoked":[{"task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","task_name":"Customer Support Analyzer","task_run_id":"019fa2da-4790-798a-9530-76940e914d17","is_error":false,"is_formatter":false,"duration_ms":1120},{"task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","task_name":"Draft Support Reply","task_run_id":"019fa2da-4790-7bff-bc7a-c397d193f25e","is_error":false,"is_formatter":true,"duration_ms":2380}],"integration_tools_invoked":[{"integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_name":"Customer Database","integration_type":"google_sheets","integration_tool_id":"019df7a2-44a0-7b09-afd0-c59cbc20126d","tool_name":"sheets_spreadsheets_values_get","principal_type":"project_default","is_error":false,"duration_ms":640}],"phase_timings":[{"phase":"llm_inference","start_ms":0,"end_ms":1450},{"phase":"integration_tool_execution","start_ms":1450,"end_ms":2090,"call_id":"call-2b3c4d5e6f70","tool_name":"sheets_spreadsheets_values_get","integration_name":"Customer Database"},{"phase":"task_tool_execution","start_ms":2090,"end_ms":4470,"call_id":"call-3c4d5e6f7081","task_run_id":"019fa2da-4790-7bff-bc7a-c397d193f25e"}],"context_usage":{"schema_version":1,"estimator_version":"task_agent_context_usage_v1","input_tokens":{"provider_total":1840,"observed_provider_total":1840,"estimated_total":1890,"uncategorized":0,"breakdown":{"skills":0,"mcp_tools":0,"task_tools":20,"input_files":0,"instructions":153,"integrations":0,"runtime_file":108,"registered_tools":0,"conversation_history":0,"current_user_message":23}},"input_files":{"estimated_tokens":0,"file_count":0,"text_file_count":0,"binary_file_count":0,"total_bytes":0},"output_tokens":{"provider_total":410,"observed_provider_total":410},"runtime_components":{"skills":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"loaded_payloads":0,"provenance":{}},"mcp_tools":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"provenance":{}},"task_tools":{"estimated_tokens":20,"tool_declarations":{"estimated_tokens":20,"count":1,"unavailable_count":0,"error_count":0},"provenance":{"manual":20}},"integrations":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"provenance":{}},"runtime_file":{"estimated_tokens":108,"tool_declarations":{"estimated_tokens":108,"count":1,"unavailable_count":0,"error_count":0},"provenance":{"manual":108}},"registered_tools":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"provenance":{}}},"metadata":{"request_count":1,"partial":false,"provider_usage_missing":false,"provider_usage_complete":true,"observed_provider_total_tokens":2250,"estimation_truncated":false,"truncated_estimate_count":0,"estimation_methods":["utf8_bytes_div_4"]}},"last_activity_at":"2026-07-27T09:14:11Z","trigger_type":"api","model_usages":[{"id":"019fa2da-4790-7fa0-9552-00540687d1cb","task_agent_run_id":"019fa2da-4790-712c-aaa2-cb8d287b620b","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","usage_scope":"reasoning","usage_type":"primary","input_tokens":1840,"output_tokens":410,"total_tokens":2250,"charged_credits":"4.10","call_count":3,"created":"2026-07-27T09:14:02Z","modified":"2026-07-27T09:14:11Z"}],"files":[],"is_chaos_run":false}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentrun"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find run [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"run","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/support-request":{"post":{"tags":["Task Agents"],"summary":"Create Task Agent Run Support Request","operationId":"createTaskAgentRunSupportRequest","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentRunSupportRequestCreate"},"example":{"run_ids":["019fa2da-4790-712c-aaa2-cb8d287b620b"],"annotation":"Reply referenced the wrong account name for a Northfield Joinery ticket — can support check why the lookup matched the wrong row?"}}}},"responses":{"200":{"description":"Support request created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentRunSupportRequestMetadata"},"example":{"id":"019fa2e2-2f00-738f-ad3d-25fa857b319b","org_id":"0190a234-5678-9abc-def0-123456789abc","project_id":"0190a234-9876-5432-10ab-cdef01234567","requested_by_user_id":"0190c234-1111-2222-3333-444444444444","annotation":"Reply referenced the wrong account name for a Northfield Joinery ticket — can support check why the lookup matched the wrong row?","status":"open","created":"2026-07-27T09:30:00Z","modified":"2026-07-27T09:30:00Z","snapshot_entries":[{"id":"019fa2e2-2f00-720e-8894-970f64e46fb3","task_agent_run_id":"019fa2da-4790-712c-aaa2-cb8d287b620b","snapshot_schema_version":1,"payload_created_at":"2026-07-27T09:30:00Z","expires_at":"2026-08-26T09:30:00Z","created":"2026-07-27T09:30:00Z","modified":"2026-07-27T09:30:00Z"}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskagentrunsupportrequest"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent_run [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent_run","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to create support request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Request support for one or more visible Task Agent runs.\n\nThe request stores metadata plus a redacted diagnostic snapshot for each listed\nrun. The response returns metadata only and never includes the support payload."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/run/{run_id}/file/{file_name}":{"get":{"tags":["Task Agents"],"summary":"Get Task Agent Run File","description":"Download a file associated with a TaskAgentRun.\n\nFiles include uploads submitted with the run and files generated by Task tools\nduring the run. The file is served with appropriate content type headers for\ninline viewing or download based on the `inline` parameter.\n\n`file_name` is the `stored_filename` from the run's `files` array, not the name\nthe caller uploaded. Each entry there also carries a ready-made `download_url`\nfor this endpoint, and a `source` of `input` or `output` saying which side of\nthe run produced it.\n\nThe response carries the stored file's own content type — a `.txt` attachment\ncomes back as `text/plain`, not as an opaque byte stream — and a\n`Content-Disposition` header naming the stored file.","operationId":"getTaskAgentRunFile","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"},"description":"The task agent run ID"},{"name":"file_name","in":"path","required":true,"schema":{"type":"string","examples":["93e38bb3-d94e-4a3e-8c80-9b8a1c1d7686.png","065d974b-86cf-4fff-a2ce-7a37a5eac037.mp3"],"title":"File Name"},"description":"The stored file name to fetch."},{"name":"inline","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Inline"},"description":"If true, serve file inline instead of as attachment"}],"responses":{"200":{"description":"File content returned successfully","content":{"application/json":{"schema":{}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"image/*":{"schema":{"type":"string","format":"binary"}},"audio/*":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string"},"example":"Docs probe fixture.\nThe quick brown fox jumps over the lazy dog.\n"}},"headers":{"Content-Disposition":{"description":"`attachment; filename=\"<stored_filename>\"`, or `inline; filename=\"<stored_filename>\"` when `inline=true`.","schema":{"type":"string"},"example":"attachment; filename=\"0633f35e-9957-4b60-8937-2838c3f825c4.txt\""},"Content-Type":{"description":"The stored file's own media type.","schema":{"type":"string"},"example":"text/plain; charset=utf-8"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentrunfile"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"The TaskAgent, the run, or the named file could not be found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"unknown_run":{"summary":"Unknown run","value":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find run_id [019f8a05-6f65-7004-af6f-7fa142935054]","resourceNotFoundError":{"field":"run_id","value":"019f8a05-6f65-7004-af6f-7fa142935054"}}}},"unknown_file":{"summary":"Run has no such file","value":{"detail":"File not found"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve run file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/session":{"get":{"tags":["Task Agents"],"summary":"List Task Agent Sessions","description":"List conversation sessions for a Task Agent.\n\nSessions group related runs together for multi-turn conversations.","operationId":"listTaskAgentSessions","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Agent Id"},"description":"The specific Task Agent to reference."}],"responses":{"200":{"description":"Session list","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskAgentSessionSummary"},"title":"Response Listtaskagentsessions"},"example":[{"session_id":"019fa2da-4790-7718-8edc-ae551b239242","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","run_count":2,"first_run":"2026-07-27T09:14:02Z","last_run":"2026-07-27T09:22:40Z","total_tokens":3390,"total_charged_credits":"6.15"},{"session_id":"019f7fd8-26e0-7bde-a9b4-b22262209480","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","run_count":1,"first_run":"2026-07-20T14:05:00Z","last_run":"2026-07-20T14:05:00Z","total_tokens":1410,"total_charged_credits":"2.35"}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskagentsessions"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to list sessions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/session/{session_id}":{"get":{"tags":["Task Agents"],"summary":"Get Session Detail","description":"Get detailed information about a specific session.\n\nReturns session summary (run count, tokens) plus individual runs, including\nphase timing data when available.","operationId":"getTaskAgentSessionDetail","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Agent Id"},"description":"The specific Task Agent to reference."},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Session Id"},"description":"The session ID (UUID format, server-generated)."}],"responses":{"200":{"description":"Session detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentSessionDetail"},"example":{"session_id":"019fa2da-4790-7718-8edc-ae551b239242","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","run_count":2,"first_run":"2026-07-27T09:14:02Z","last_run":"2026-07-27T09:22:40Z","total_tokens":3390,"total_charged_credits":"6.15","runs":[{"id":"019fa2da-4790-712c-aaa2-cb8d287b620b","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","user_id":"0190c234-1111-2222-3333-444444444444","actor_user_id":"0190c234-1111-2222-3333-444444444444","actor_basis":"direct_user","execution_surface":"task_agent_api","execution_source_id":"019df849-e106-3301-5894-291b4c9c6cab","invocation_id":"019fa2da-4790-7e73-b7af-bfd124a96ed6","invocation_ids":["019fa2da-4790-7e73-b7af-bfd124a96ed6"],"is_continuation":false,"primary_llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","used_fallback_model":false,"input_tokens":1840,"output_tokens":410,"total_tokens":2250,"charged_credits":"4.10","total_charged_credits":"4.10","created":"2026-07-27T09:14:02Z","completed":"2026-07-27T09:14:11Z","duration_ms":9130,"status":"completed","is_error":false,"approval_request_ids":[],"approval_requests":[],"had_task_tool_fail":false,"had_mcp_tool_fail":false,"had_integration_tool_fail":false,"task_tools_invoked":[{"task_id":"019df7a2-44a0-7f6b-8a18-d81df57049d0","task_revision_id":"019df7a2-44a0-75d6-b036-4e86f6d45302","task_name":"Customer Support Analyzer","task_run_id":"019fa2da-4790-798a-9530-76940e914d17","is_error":false,"is_formatter":false,"duration_ms":1120},{"task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","task_name":"Draft Support Reply","task_run_id":"019fa2da-4790-7bff-bc7a-c397d193f25e","is_error":false,"is_formatter":true,"duration_ms":2380}],"integration_tools_invoked":[{"integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_name":"Customer Database","integration_type":"google_sheets","integration_tool_id":"019df7a2-44a0-7b09-afd0-c59cbc20126d","tool_name":"sheets_spreadsheets_values_get","principal_type":"project_default","is_error":false,"duration_ms":640}],"phase_timings":[{"phase":"llm_inference","start_ms":0,"end_ms":1450},{"phase":"integration_tool_execution","start_ms":1450,"end_ms":2090,"call_id":"call-2b3c4d5e6f70","tool_name":"sheets_spreadsheets_values_get","integration_name":"Customer Database"},{"phase":"task_tool_execution","start_ms":2090,"end_ms":4470,"call_id":"call-3c4d5e6f7081","task_run_id":"019fa2da-4790-7bff-bc7a-c397d193f25e"}],"context_usage":{"schema_version":1,"estimator_version":"task_agent_context_usage_v1","input_tokens":{"provider_total":1840,"observed_provider_total":1840,"estimated_total":1890,"uncategorized":0,"breakdown":{"skills":0,"mcp_tools":0,"task_tools":20,"input_files":0,"instructions":153,"integrations":0,"runtime_file":108,"registered_tools":0,"conversation_history":0,"current_user_message":23}},"input_files":{"estimated_tokens":0,"file_count":0,"text_file_count":0,"binary_file_count":0,"total_bytes":0},"output_tokens":{"provider_total":410,"observed_provider_total":410},"runtime_components":{"skills":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"loaded_payloads":0,"provenance":{}},"mcp_tools":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"provenance":{}},"task_tools":{"estimated_tokens":20,"tool_declarations":{"estimated_tokens":20,"count":1,"unavailable_count":0,"error_count":0},"provenance":{"manual":20}},"integrations":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"provenance":{}},"runtime_file":{"estimated_tokens":108,"tool_declarations":{"estimated_tokens":108,"count":1,"unavailable_count":0,"error_count":0},"provenance":{"manual":108}},"registered_tools":{"estimated_tokens":0,"tool_declarations":{"estimated_tokens":0,"count":0,"unavailable_count":0,"error_count":0},"provenance":{}}},"metadata":{"request_count":1,"partial":false,"provider_usage_missing":false,"provider_usage_complete":true,"observed_provider_total_tokens":2250,"estimation_truncated":false,"truncated_estimate_count":0,"estimation_methods":["utf8_bytes_div_4"]}},"last_activity_at":"2026-07-27T09:14:11Z","trigger_type":"api","model_usages":[{"id":"019fa2da-4790-7fa0-9552-00540687d1cb","task_agent_run_id":"019fa2da-4790-712c-aaa2-cb8d287b620b","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","usage_scope":"reasoning","usage_type":"primary","input_tokens":1840,"output_tokens":410,"total_tokens":2250,"charged_credits":"4.10","call_count":3,"created":"2026-07-27T09:14:02Z","modified":"2026-07-27T09:14:11Z"}],"files":[],"is_chaos_run":false},{"id":"019fa2e2-2f00-7be2-bcf0-f056f44f700a","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","session_id":"019fa2da-4790-7718-8edc-ae551b239242","adk_session_user_id":"0190c234-1111-2222-3333-444444444444","user_id":"0190c234-1111-2222-3333-444444444444","actor_user_id":"0190c234-1111-2222-3333-444444444444","actor_basis":"direct_user","execution_surface":"task_agent_approval_resume","execution_source_id":"019fa2e2-2f00-71c7-aee7-539ab31cd302","invocation_id":"019fa2e2-2f00-7a54-9f70-cd49ad3571d2","invocation_ids":["019fa2e2-2f00-7a54-9f70-cd49ad3571d2"],"is_continuation":true,"primary_llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","used_fallback_model":false,"input_tokens":960,"output_tokens":180,"total_tokens":1140,"charged_credits":"2.05","total_charged_credits":"2.05","created":"2026-07-27T09:22:40Z","completed":"2026-07-27T09:24:20Z","duration_ms":100000,"status":"completed","is_error":false,"approval_request_ids":["019fa2e2-2f00-71c7-aee7-539ab31cd302"],"approval_requests":[{"id":"019fa2e2-2f00-71c7-aee7-539ab31cd302","status":"approved","tool_type":"integration","tool_name":"sheets_spreadsheets_values_append","requested_at":"2026-07-27T09:22:41Z","decided_at":"2026-07-27T09:24:15Z","requested_by_user_id":"0190c234-1111-2222-3333-444444444444","decided_by_user_id":"019df7a2-44a0-7f54-8478-e19c351d1cc8","decision_note":"Approved — logging the resolved ticket is fine."}],"had_task_tool_fail":false,"had_mcp_tool_fail":false,"had_integration_tool_fail":false,"task_tools_invoked":[{"task_id":"019df7a2-44a0-7186-92a6-a8e45e78537b","task_revision_id":"019df7a2-44a0-78c4-ba7b-6ae382a6253a","task_name":"Draft Support Reply","task_run_id":"019fa2e2-2f00-7f38-a32e-85d18e953d52","is_error":false,"is_formatter":true,"duration_ms":1360}],"integration_tools_invoked":[{"integration_id":"019df7a2-44a0-7a75-ae4f-4c8edcdac22e","integration_name":"Customer Database","integration_type":"google_sheets","integration_tool_id":"019df7a2-44a0-7923-9ea9-87be4ba93be9","tool_name":"sheets_spreadsheets_values_append","principal_type":"project_default","is_error":false,"duration_ms":510}],"last_activity_at":"2026-07-27T09:24:20Z","trigger_type":"api","model_usages":[{"id":"019fa2e2-2f00-76c3-8b69-2a582554fe03","task_agent_run_id":"019fa2e2-2f00-7be2-bcf0-f056f44f700a","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","usage_scope":"reasoning","usage_type":"primary","input_tokens":960,"output_tokens":180,"total_tokens":1140,"charged_credits":"2.05","call_count":2,"created":"2026-07-27T09:22:40Z","modified":"2026-07-27T09:24:20Z"}],"files":[],"is_chaos_run":false}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentsessiondetail"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find session [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"session","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve session detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}},"delete":{"tags":["Task Agents"],"summary":"Delete Session","description":"Delete a conversation session and all its runs.\n\nRemoves:\n- ADK session data (encrypted conversation history)\n- All TaskAgentRun records for the session\n\nCannot delete a session with active runs.","operationId":"deleteTaskAgentSession","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Agent Id"},"description":"The specific Task Agent to reference."},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Session Id"},"description":"The session ID (UUID format, server-generated)."}],"responses":{"204":{"description":"Session deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletetaskagentsession"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find session [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"session","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"409":{"description":"Session has active runs"},"500":{"description":"Internal Server Error - Failed to delete session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/run/{run_id}/events":{"get":{"tags":["Task Agents"],"summary":"Get Run Events","description":"Get conversation events for a specific TaskAgentRun.\n\nReturns the full conversation history from the ADK session including:\n- User messages\n- Agent responses\n- Tool calls and results\n- Metadata-only memory compaction events, including token-threshold metadata when\n  token-aware compaction was active\n- Error messages (if any)\n\nEvents are returned in chronological order. The example below is the full event\nsequence for a run that classifies an inbound email with a Task tool, looks up\nthe account through a connected integration tool, and drafts the reply through\na Task tool marked as the output formatter — the same run shown by\n`GET .../run/{run_id}` and streamed live by `POST .../run`.","operationId":"getTaskAgentRunEvents","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Agent Id"},"description":"The specific Task Agent to reference."},{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Run Id"},"description":"The specific Run to reference."},{"name":"include_history","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include History"},"description":"Include full session history, not just this run's events"}],"responses":{"200":{"description":"Run events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentRunEventsResponse"},"example":{"run_id":"019fa2da-4790-712c-aaa2-cb8d287b620b","session_id":"019fa2da-4790-7718-8edc-ae551b239242","events":[{"id":"019fa2da-4790-76ea-a59f-d21e748d05b2","author":"user","content":"Subject: Charged twice for June invoice\n\nHi, I think we've been billed twice for our June bookkeeping retainer — I can see two charges of £450 on the 3rd and the 5th. Could someone check our account and let me know what's going on? Our account email is dana@northfieldjoinery.co.uk.\n\nThanks,\nDana","timestamp":"2026-07-27T09:14:02Z","event_type":"user_message","files":[]},{"id":"019fa2da-4790-7fc1-8499-87f7e92332e6","author":"support_triage_agent","timestamp":"2026-07-27T09:14:03Z","event_type":"tool_call","tool_calls":[{"name":"customer_support_analyzer","args":{"message":"Subject: Charged twice for June invoice\n\nHi, I think we've been billed twice for our June bookkeeping retainer — I can see two charges of £450 on the 3rd and the 5th. Could someone check our account and let me know what's going on? Our account email is dana@northfieldjoinery.co.uk.\n\nThanks,\nDana"}}],"files":[]},{"id":"019fa2da-4790-7990-8af1-933d1b9a8538","author":"support_triage_agent","timestamp":"2026-07-27T09:14:04Z","event_type":"tool_result","tool_results":[{"name":"customer_support_analyzer","tool_result_type":"task","task_run_id":"019fa2da-4790-798a-9530-76940e914d17","is_formatter_output":false,"result":{"result":{"sentiment":"concerned","category":"billing_dispute","suggested_response":"Confirm the duplicate charge, check the account, and let the customer know a refund will be reviewed."},"task_run_id":"019fa2da-4790-798a-9530-76940e914d17"}}],"files":[]},{"id":"019fa2da-4790-7be8-8bfe-06792d763e98","author":"support_triage_agent","timestamp":"2026-07-27T09:14:05Z","event_type":"tool_call","tool_calls":[{"name":"sheets_spreadsheets_values_get","args":{"spreadsheet_id":"1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms","range":"Customers!A2:F500"}}],"files":[]},{"id":"019fa2da-4790-7023-9935-659f10bbf266","author":"support_triage_agent","timestamp":"2026-07-27T09:14:06Z","event_type":"tool_result","tool_results":[{"name":"sheets_spreadsheets_values_get","tool_result_type":"generic","is_formatter_output":false,"result":{"range":"Customers!A2:F2","majorDimension":"ROWS","values":[["NJ-1042","Dana Whitfield","dana@northfieldjoinery.co.uk","Bookkeeping Retainer - Standard","active","No prior disputes"]]}}],"files":[]},{"id":"019fa2da-4790-7b9e-8229-2b44fb74adde","author":"support_triage_agent","timestamp":"2026-07-27T09:14:08Z","event_type":"tool_call","tool_calls":[{"name":"draft_support_reply","args":{"ticket_summary":"Customer reports being charged twice for the June retainer (£450 x2 on 3 and 5 July).","customer_record":{"account_id":"NJ-1042","name":"Dana Whitfield","plan":"Bookkeeping Retainer - Standard","status":"active"}}}],"files":[]},{"id":"019fa2da-4790-76b2-a83e-5e15c385e5f5","author":"support_triage_agent","timestamp":"2026-07-27T09:14:10Z","event_type":"formatted_output","tool_results":[{"name":"draft_support_reply","tool_result_type":"task","task_run_id":"019fa2da-4790-7bff-bc7a-c397d193f25e","is_formatter_output":true,"result":{"result":"Hi Dana,\n\nThanks for flagging this — I can see two £450 charges against your Bookkeeping Retainer account (NJ-1042) on 3 and 5 July, and that does look like a duplicate. There are no other disputes on file, so this should be straightforward.\n\nI can't issue the refund myself, but I've flagged it to the team and someone will confirm and process it within one business day.\n\nThanks for your patience,\nSupport Triage","task_run_id":"019fa2da-4790-7bff-bc7a-c397d193f25e"}}],"files":[]}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentrunevents"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find run [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"run","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve run events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/iam/members":{"get":{"tags":["Task Agents"],"summary":"IAM - List Task Agent Members","description":"Lists all members that have been granted direct access to the task_agent.","operationId":"task_agent_iam_org_org_id_project_project_id_task-agent_task_agent_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view","task_agent:view_members"]}],"parameters":[{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Task Agent members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Agent Iam Org Org Id Project Project Id Task-Agent Task Agent Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/iam/members/{member}":{"get":{"tags":["Task Agents"],"summary":"IAM - Lookup Task Agent Member","description":"Retrieve a specific member that has been granted direct access to the task_agent.","operationId":"task_agent_iam_org_org_id_project_project_id_task-agent_task_agent_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view","task_agent:view_members"]}],"parameters":[{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Task Agent member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Agent Iam Org Org Id Project Project Id Task-Agent Task Agent Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Task Agents"],"summary":"IAM - Update Task Agent Member","description":"Update the roles that a member holds on the task_agent.","operationId":"task_agent_iam_org_org_id_project_project_id_task-agent_task_agent_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task_AgentIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Task Agent member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Task Agent Iam Org Org Id Project Project Id Task-Agent Task Agent Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Agent Iam Org Org Id Project Project Id Task-Agent Task Agent Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/iam/test":{"post":{"tags":["Task Agents"],"summary":"IAM - Test Task Agent Permissions","description":"Test the permissions that the caller (or another subject) holds on the task_agent.","operationId":"task_agent_iam_org_org_id_project_project_id_task-agent_task_agent_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task_AgentIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Task Agent permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Task Agent Iam Org Org Id Project Project Id Task-Agent Task Agent Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Agent Iam Org Org Id Project Project Id Task-Agent Task Agent Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/eval/set":{"post":{"tags":["Task Agent Evals"],"summary":"Create TaskAgent Eval Set","operationId":"createTaskAgentEvalSet","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentEvalSetCreate"},"examples":{"from_runs":{"summary":"Create from reference runs","value":{"name":"Support quality golden set","description":"Reference conversations for support triage.","task_agent_run_ids":["0190b234-1111-2222-3333-444444444444","0190b234-5555-6666-7777-888888888888"]}}}}}},"responses":{"201":{"description":"TaskAgent eval set created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentEvalSetResponse"},"examples":{"Create from reference runs":{"summary":"Create from reference runs","value":{"id":"0190d234-1111-2222-3333-444444444444","name":"Support quality golden set","description":"Reference conversations for support triage.","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-27T18:53:36.814214Z","modified":"2026-07-27T18:53:36.814214Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444","task_agent_run_ids":["0190b234-1111-2222-3333-444444444444","0190b234-5555-6666-7777-888888888888"]}}}}}},"400":{"description":"Bad Request - Invalid eval set\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"},{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid eval set"}}}},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskagentevalset"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to create Task Agent eval set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a reusable TaskAgent eval set from completed, replayable TaskAgent runs. Reference inputs and outputs are snapshotted for stable future evals but are not exposed in this API version."},"get":{"tags":["Task Agent Evals"],"summary":"List TaskAgent Eval Sets","operationId":"listTaskAgentEvalSets","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"TaskAgent eval sets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskAgentEvalSetResponse_"},"example":{"results":[{"id":"0190d234-1111-2222-3333-444444444444","name":"Support quality golden set","description":"Reference conversations for support triage.","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-27T18:53:36.814214Z","modified":"2026-07-27T18:53:36.814214Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444","task_agent_run_ids":["0190b234-1111-2222-3333-444444444444","0190b234-5555-6666-7777-888888888888"]}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"description":"Bad request or TaskAgent eval business validation failure","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"},{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}]}}}},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskagentevalsets"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list Task Agent eval sets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List TaskAgent eval sets visible to the caller. Viewers without full run visibility only see eval artifacts they created."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/eval/set/{task_agent_eval_set_id}":{"get":{"tags":["Task Agent Evals"],"summary":"Get TaskAgent Eval Set","operationId":"getTaskAgentEvalSet","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"task_agent_eval_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Eval Set Id"},"description":"The TaskAgent eval set ID"}],"responses":{"200":{"description":"TaskAgent eval set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentEvalSetResponse"},"example":{"id":"0190d234-1111-2222-3333-444444444444","name":"Support quality golden set","description":"Reference conversations for support triage.","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-27T18:53:36.814214Z","modified":"2026-07-27T18:53:36.814214Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444","task_agent_run_ids":["0190b234-1111-2222-3333-444444444444","0190b234-5555-6666-7777-888888888888"]}}}},"400":{"description":"Bad request or TaskAgent eval business validation failure","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"},{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}]}}}},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentevalset"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"404":{"description":"Task Agent eval set not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent_eval_set [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent_eval_set","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agent eval set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Get one TaskAgent eval set by ID. The response includes preserved source TaskAgent run IDs but not encrypted snapshot text."},"post":{"tags":["Task Agent Evals"],"summary":"Update TaskAgent Eval Set","operationId":"updateTaskAgentEvalSet","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"task_agent_eval_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Eval Set Id"},"description":"The TaskAgent eval set ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentEvalSetUpdate"},"examples":{"from_runs":{"summary":"Create from reference runs","value":{"name":"Support quality golden set","description":"Reference conversations for support triage.","task_agent_run_ids":["0190b234-1111-2222-3333-444444444444","0190b234-5555-6666-7777-888888888888"]}}}}}},"responses":{"200":{"description":"TaskAgent eval set updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentEvalSetResponse"},"examples":{"Create from reference runs":{"summary":"Create from reference runs","value":{"id":"0190d234-1111-2222-3333-444444444444","name":"Support quality golden set","description":"Reference conversations for support triage.","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-27T18:53:36.814214Z","modified":"2026-07-27T18:53:36.814214Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444","task_agent_run_ids":["0190b234-1111-2222-3333-444444444444","0190b234-5555-6666-7777-888888888888"]}}}}}},"400":{"description":"Bad Request - Invalid eval set\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"},{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid eval set"}}}},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatetaskagentevalset"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"404":{"description":"Task Agent eval set not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent_eval_set [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent_eval_set","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to update Task Agent eval set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update a TaskAgent eval set name, description, or reference runs. Replacing reference runs creates fresh encrypted snapshots and preserves the submitted order."},"delete":{"tags":["Task Agent Evals"],"summary":"Delete TaskAgent Eval Set","operationId":"deleteTaskAgentEvalSet","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"task_agent_eval_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Eval Set Id"},"description":"The TaskAgent eval set ID"}],"responses":{"204":{"description":"TaskAgent eval set deleted"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletetaskagentevalset"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"404":{"description":"Task Agent eval set not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent_eval_set [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent_eval_set","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"409":{"description":"Eval set is referenced by a pending or running eval run","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to delete Task Agent eval set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Delete a TaskAgent eval set when it is not referenced by a pending or running eval run."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/eval/run":{"post":{"tags":["Task Agent Evals"],"summary":"Start TaskAgent Eval Run","operationId":"createTaskAgentEvalRun","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:run"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentEvalRunCreate"},"examples":{"from_eval_set":{"summary":"Run against an eval set","value":{"eval_set_id":"0190d234-1111-2222-3333-444444444444","candidate_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","judge_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41"}},"from_recent_runs":{"summary":"Run against recent completed runs","value":{"last_n":5,"candidate_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","judge_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41"}},"custom_judge_policy":{"summary":"Run with a custom judge objective and rubric","value":{"eval_set_id":"0190d234-1111-2222-3333-444444444444","candidate_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","judge_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","judge_config":{"objective":"Determine whether the response resolves the support request safely and usefully.","rubric":["Correctly identifies the underlying problem.","Provides actionable next steps.","Does not promise an unsupported refund.","Does not expose internal operational details."]}}}}}}},"responses":{"201":{"description":"TaskAgent eval run created and enqueued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentEvalRunResponse"},"examples":{"Run against an eval set":{"summary":"Run against an eval set","value":{"id":"0190e234-1111-2222-3333-444444444444","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","project_id":"0190a234-9876-5432-10ab-cdef01234567","candidate_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","eval_set_id":"0190d234-1111-2222-3333-444444444444","status":"pending","pass_count":0,"fail_count":0,"error_count":0,"created":"2026-07-27T18:54:27.451807Z","modified":"2026-07-27T18:54:28.185742Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444","task_agent_run_ids":["0190b234-1111-2222-3333-444444444444","0190b234-5555-6666-7777-888888888888"],"pass_rate":null}}}}}},"400":{"description":"Candidate revision matches every reference run's revision, or the eval set/recent-runs selection is otherwise invalid","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"},{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}]},"example":{"detail":"Candidate revision matches all reference runs. Choose a different candidate revision or references from another revision."}}}},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskagentevalrun"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have run permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"run"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"404":{"description":"Task Agent eval set not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent_eval_set [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent_eval_set","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/HTTPValidationError"},{"type":"object","properties":{"detail":{"type":"object"}},"required":["detail"]}]},"example":{"detail":[{"type":"uuid_parsing","loc":["body","candidate_revision_id"],"msg":"Input should be a valid UUID, invalid character: found `n` at 1","input":"not-a-uuid","ctx":{"error":"invalid character: found `n` at 1"}}]}}}},"503":{"description":"TaskAgent eval background execution could not be enqueued","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to create Task Agent eval run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a TaskAgent eval run and enqueue background execution. Callers are responsible for understanding candidate run side effects, external tool or integration mutations, and quota usage before starting an eval. An optional judge_config supplies one objective and an ordered rubric for the complete run. The reference remains a known-good comparator, and every rubric criterion must pass. Omitting judge_config uses the standard functional-equivalence rubric. The resolved configuration is returned by run detail. Objective and rubric text is sent to the selected external judge model provider and is visible to callers authorized to view TaskAgent Eval run detail. The candidate revision must differ from every reference run's revision — evaluating a candidate against itself is rejected."},"get":{"tags":["Task Agent Evals"],"summary":"List TaskAgent Eval Runs","operationId":"listTaskAgentEvalRuns","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"TaskAgent eval runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskAgentEvalRunResponse_"},"example":{"results":[{"id":"0190e234-1111-2222-3333-444444444444","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","project_id":"0190a234-9876-5432-10ab-cdef01234567","candidate_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","eval_set_id":"0190d234-1111-2222-3333-444444444444","status":"completed","pass_count":1,"fail_count":1,"error_count":0,"started_at":"2026-07-27T18:54:28.153043Z","completed_at":"2026-07-27T18:54:37.298606Z","last_activity_at":"2026-07-27T18:54:37.298606Z","created":"2026-07-27T18:54:27.451807Z","modified":"2026-07-27T18:54:28.185742Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444","task_agent_run_ids":["0190b234-1111-2222-3333-444444444444","0190b234-5555-6666-7777-888888888888"],"pass_rate":0.5}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"description":"Bad request or TaskAgent eval business validation failure","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"},{"type":"object","properties":{"detail":{"type":"string"}},"required":["detail"]}]}}}},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskagentevalruns"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"404":{"description":"Task Agent not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list Task Agent eval runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List TaskAgent eval runs visible to the caller. Viewers without full run visibility only see eval runs they created. Each entry is the compact summary shape — call get Task Agent Eval Run for verdicts and metrics."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/eval/run/{task_agent_eval_run_id}":{"get":{"tags":["Task Agent Evals"],"summary":"Get TaskAgent Eval Run","operationId":"getTaskAgentEvalRun","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"task_agent_eval_run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Eval Run Id"},"description":"The TaskAgent eval run ID"}],"responses":{"200":{"description":"TaskAgent eval run detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentEvalRunDetailResponse"},"example":{"id":"0190e234-1111-2222-3333-444444444444","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","project_id":"0190a234-9876-5432-10ab-cdef01234567","candidate_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","eval_set_id":"0190d234-1111-2222-3333-444444444444","status":"completed","pass_count":1,"fail_count":1,"error_count":0,"started_at":"2026-07-27T18:54:28.153043Z","completed_at":"2026-07-27T18:54:37.298606Z","last_activity_at":"2026-07-27T18:54:37.298606Z","created":"2026-07-27T18:54:27.451807Z","modified":"2026-07-27T18:54:28.185742Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444","task_agent_run_ids":["0190b234-1111-2222-3333-444444444444","0190b234-5555-6666-7777-888888888888"],"pass_rate":0.5,"judge_model":{"name":"gpt-4o-mini","provider":"OpenAI"},"metrics":{"token_cost":{"reference_avg":266.0,"candidate_avg":618.0,"delta_pct":132.33},"charged_credits":{"reference_avg":2.0,"candidate_avg":1.0,"delta_pct":-50.0},"duration_ms":{"reference_avg":2945.0,"candidate_avg":7250.0,"delta_pct":146.18}},"results":[{"id":"0190e234-dddd-eeee-ffff-000011112222","eval_run_id":"0190e234-1111-2222-3333-444444444444","eval_case_id":"0190e234-9999-aaaa-bbbb-cccccccccccc","reference_run_id":"0190b234-1111-2222-3333-444444444444","candidate_run_id":"0190e234-5555-6666-7777-888888888888","verdict":"fail","reasoning":"The Candidate output does not provide a classification for the support request, which is a key requirement of the user input.","judge_input_tokens":384,"judge_output_tokens":54,"is_error":false,"created":"2026-07-27T18:54:37.208994Z","metrics":{"reference":{"total_tokens":266,"charged_credits":"2.00","duration_ms":2945.0},"candidate":{"total_tokens":618,"charged_credits":"1.00","duration_ms":7250.0}}}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskagentevalrun"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for Task Agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The Task Agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"404":{"description":"Task Agent eval run not found","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{}},"required":["detail"],"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_agent_eval_run [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_agent_eval_run","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve Task Agent eval run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Get TaskAgent eval run detail, including verdicts, aggregate metrics, and per-result run metrics when the underlying source rows still exist. The response includes the immutable custom judge configuration when one was supplied; its text is visible under these existing run-detail authorization rules. Encrypted reference and candidate output snapshots are not exposed."}},"/org/{org_id}/project/{project_id}/task_forwarder_type":{"get":{"tags":["Task Forwarders"],"summary":"List Task Forwarder Types","operationId":"listTaskForwarderTypes","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Available forwarder types with configuration schemas","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskForwarderTypeInfo"},"title":"Response Listtaskforwardertypes"},"example":[{"type":"webhook","name":"Webhook","description":"Forward task results via HTTP POST to a webhook URL","config_schema":{"title":"TaskForwarderConfig","type":"object","properties":{"destination_url":{"type":"string","title":"Destination Url","description":"The URL where Task Run result will be forwarded. Must be a valid HTTPS URL."}},"required":["destination_url"]},"config_sensitive_schema":{"title":"TaskForwarderSensitiveConfig","type":"object","properties":{"signing_key":{"type":"string","title":"Signing Key","description":"A secret key used to sign the forwarded data for verification purposes."}},"required":["signing_key"]}},{"type":"email","name":"Email","description":"Send task results via email with customizable templates","config_schema":{"title":"TaskForwarderEmailConfig","type":"object","properties":{"recipient_emails":{"type":"array","items":{"type":"string","format":"email"},"title":"Recipient Emails","minItems":1,"description":"List of email addresses to send task results to."},"subject_template":{"type":"string","title":"Subject Template","description":"Email subject template with {variable} placeholders for task data."},"body_template":{"type":"string","title":"Body Template","description":"Email body template with {variable} placeholders for task data."},"cc_emails":{"anyOf":[{"type":"array","items":{"type":"string","format":"email"}},{"type":"null"}],"title":"Cc Emails","description":"Optional list of CC email addresses."},"bcc_emails":{"anyOf":[{"type":"array","items":{"type":"string","format":"email"}},{"type":"null"}],"title":"Bcc Emails","description":"Optional list of BCC email addresses."}},"required":["recipient_emails","subject_template","body_template"]}}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskforwardertypes"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list forwarder types","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List all available task forwarder types with their configuration schemas.\n\n**Note**: This endpoint returns a plain array of forwarder types, not a paginated response. All available types are returned in a single request.\n\nReturns metadata for each forwarder type to help frontends build dynamic configuration UIs:\n- **webhook**: HTTP POST to external endpoints with optional HMAC signing\n- **email**: Send task results via email with customizable templates\n\nEach type includes:\n- JSON Schema for required configuration fields\n- JSON Schema for sensitive configuration (if applicable)\n- Field descriptions and validation rules\n\nUse this endpoint to dynamically render appropriate form fields based on the selected forwarder type."}},"/org/{org_id}/project/{project_id}/task_forwarder":{"post":{"tags":["Task Forwarders"],"summary":"Create Task Forwarder","operationId":"createTaskForwarder","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_task_forwarder"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookForwarderCreate"},{"$ref":"#/components/schemas/EmailForwarderCreate"}],"title":"Task Forwarder"},"examples":{"webhook":{"summary":"Webhook Forwarder","value":{"name":"CRM Order Sync","description":"Forwards completed order-classification results to the CRM webhook.","forwarder_type":"webhook","config":{"destination_url":"https://crm.internal.acme-logistics.com/webhooks/rightbrain"},"config_sensitive":{"signing_key":"whsec_9f2c9d9b7a4e4b6c8f0a1b2c3d4e5f60"}}},"email":{"summary":"Email Forwarder","value":{"name":"Weekly Report Email","description":"Emails task run results to the operations team.","forwarder_type":"email","config":{"recipient_emails":["ops@acme-logistics.com"],"subject_template":"Task completed: {task_name}","body_template":"The task {task_name} finished with status {status}."}}}}}}},"responses":{"200":{"description":"Task forwarder created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskForwarder"},"examples":{"Webhook Forwarder":{"summary":"Webhook Forwarder","value":{"id":"0197d3e5-5e7f-7d24-b160-7c8d9e0f1a2b","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"CRM Order Sync","description":"Forwards completed order-classification results to the CRM webhook.","forwarder_type":"webhook","config":{"destination_url":"https://crm.internal.acme-logistics.com/webhooks/rightbrain"},"config_sensitive":{"signing_key":"whsec_9f2c9d9b7a4e4b6c8f0a1b2c3d4e5f60"},"created":"2026-06-15T08:20:00Z","modified":"2026-06-15T08:20:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid configuration"}}},"description":"Bad Request - Invalid configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskforwarder"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_task_forwarder permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_task_forwarder"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid configuration\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid configuration","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to create forwarder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a new task forwarder to automatically route task outputs.\n\nTask forwarders enable:\n- Webhook notifications when tasks complete\n- Email notifications with customizable templates\n\nConfiguration varies by forwarder type:\n- **webhook**: HTTP POST to external endpoints with optional HMAC signing\n- **email**: Send task results via email with customizable subject and body templates\n\nUse `GET /task_forwarder_type` to retrieve the complete configuration schema for each type."},"get":{"tags":["Task Forwarders"],"summary":"List Task Forwarders","operationId":"listTaskForwarders","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_task"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"Task forwarders retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskForwarder_"},"examples":{"mixed_forwarders":{"summary":"Mixed Forwarder Types","value":{"results":[{"id":"0197e4f6-6f80-7e35-8271-8d9e0f1a2b3c","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"Support Team Slack Alert","description":"Posts a Slack notification whenever a support-ticket task run completes.","forwarder_type":"webhook","config":{"destination_url":"https://hooks.slack.com/services/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"},"created":"2026-06-20T16:45:00Z","modified":"2026-06-20T16:45:00Z"},{"id":"0198f607-7091-7f46-9382-9e0f1a2b3c4d","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"Weekly Report Email","description":"Emails task run results to the operations team.","forwarder_type":"email","config":{"recipient_emails":["ops@acme-logistics.com"],"subject_template":"Task completed: {task_name}","body_template":"The task {task_name} finished with status {status}."},"created":"2026-07-05T12:00:00Z","modified":"2026-07-05T12:00:00Z"}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid pagination"}}},"description":"Bad Request - Invalid pagination\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskforwarders"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_task permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_task"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to list forwarders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List all task forwarders for the project.\n\nReturns configured forwarders with their type-specific configuration."}},"/org/{org_id}/project/{project_id}/task_forwarder/{task_forwarder_id}":{"post":{"tags":["Task Forwarders"],"summary":"Update Task Forwarder","operationId":"updateTaskForwarder","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_forwarder:edit"]}],"parameters":[{"name":"task_forwarder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Forwarder Id"},"description":"The specific Task to reference."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/WebhookForwarderUpdate"},{"$ref":"#/components/schemas/EmailForwarderUpdate"}],"title":"Task Forwarder"},"examples":{"update_destination":{"summary":"Update Webhook Destination","value":{"forwarder_type":"webhook","config":{"destination_url":"https://crm.internal.acme-logistics.com/webhooks/rightbrain/v2"}}}}}}},"responses":{"200":{"description":"Task forwarder updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskForwarder"},"examples":{"Update Webhook Destination":{"summary":"Update Webhook Destination","value":{"id":"0197d3e5-5e7f-7d24-b160-7c8d9e0f1a2b","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"CRM Order Sync","description":"Forwards completed order-classification results to the CRM webhook.","forwarder_type":"webhook","config":{"destination_url":"https://crm.internal.acme-logistics.com/webhooks/rightbrain/v2"},"config_sensitive":{"signing_key":"whsec_9f2c9d9b7a4e4b6c8f0a1b2c3d4e5f60"},"created":"2026-06-15T08:20:00Z","modified":"2026-07-20T09:30:00Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid configuration"}}},"description":"Bad Request - Invalid configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatetaskforwarder"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_forwarder [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_forwarder","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task forwarder\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task forwarder belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid configuration\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid configuration","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task forwarder not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_forwarder [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_forwarder","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to update forwarder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update task forwarder configuration.\n\nModifiable fields:\n- Name and description\n- Type-specific configuration (`config`, `config_sensitive`)\n\nNote: `forwarder_type` must match the forwarder's existing type."},"get":{"tags":["Task Forwarders"],"summary":"Get Task Forwarder","operationId":"getTaskForwarder","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_forwarder:view"]}],"parameters":[{"name":"task_forwarder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Forwarder Id"},"description":"The specific Task to reference."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Task forwarder details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskForwarder"},"example":{"id":"0197e4f6-6f80-7e35-8271-8d9e0f1a2b3c","project_id":"0190a234-9876-5432-10ab-cdef01234567","name":"Support Team Slack Alert","description":"Posts a Slack notification whenever a support-ticket task run completes.","forwarder_type":"webhook","config":{"destination_url":"https://hooks.slack.com/services/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"},"created":"2026-06-20T16:45:00Z","modified":"2026-06-20T16:45:00Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskforwarder"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_forwarder [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_forwarder","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task forwarder\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task forwarder belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task forwarder not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_forwarder [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_forwarder","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve forwarder","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve detailed information about a specific task forwarder.\n\nReturns the forwarder's complete type-specific configuration."}},"/org/{org_id}/project/{project_id}/task_forwarder/{task_forwarder_id}/iam/members":{"get":{"tags":["Task Forwarders"],"summary":"IAM - List Task Forwarder Members","description":"Lists all members that have been granted direct access to the task_forwarder.","operationId":"task_forwarder_iam_org_org_id_project_project_id_task_forwarder_task_forwarder_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_forwarder:view","task_forwarder:view_members"]}],"parameters":[{"name":"task_forwarder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Forwarder Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Task Forwarder members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Forwarder Iam Org Org Id Project Project Id Task Forwarder Task Forwarder Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task_forwarder/{task_forwarder_id}/iam/members/{member}":{"get":{"tags":["Task Forwarders"],"summary":"IAM - Lookup Task Forwarder Member","description":"Retrieve a specific member that has been granted direct access to the task_forwarder.","operationId":"task_forwarder_iam_org_org_id_project_project_id_task_forwarder_task_forwarder_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_forwarder:view","task_forwarder:view_members"]}],"parameters":[{"name":"task_forwarder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Forwarder Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Task Forwarder member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Forwarder Iam Org Org Id Project Project Id Task Forwarder Task Forwarder Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Task Forwarders"],"summary":"IAM - Update Task Forwarder Member","description":"Update the roles that a member holds on the task_forwarder.","operationId":"task_forwarder_iam_org_org_id_project_project_id_task_forwarder_task_forwarder_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_forwarder:view"]}],"parameters":[{"name":"task_forwarder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Forwarder Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task_ForwarderIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Task Forwarder member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Task Forwarder Iam Org Org Id Project Project Id Task Forwarder Task Forwarder Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Forwarder Iam Org Org Id Project Project Id Task Forwarder Task Forwarder Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task_forwarder/{task_forwarder_id}/iam/test":{"post":{"tags":["Task Forwarders"],"summary":"IAM - Test Task Forwarder Permissions","description":"Test the permissions that the caller (or another subject) holds on the task_forwarder.","operationId":"task_forwarder_iam_org_org_id_project_project_id_task_forwarder_task_forwarder_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_forwarder:view"]}],"parameters":[{"name":"task_forwarder_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Forwarder Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task_ForwarderIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Task Forwarder permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Task Forwarder Iam Org Org Id Project Project Id Task Forwarder Task Forwarder Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Forwarder Iam Org Org Id Project Project Id Task Forwarder Task Forwarder Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task_mcp_server/authorize":{"get":{"tags":["Task MCP Servers"],"summary":"Authorize MCP Server","operationId":"authorizeMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_task_mcp_server"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"server_url","in":"query","required":true,"schema":{"type":"string","format":"uri","minLength":1,"maxLength":2083,"title":"Server Url"},"description":"The remote MCP server's URL, as an http(s) URL."},{"name":"redirect_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect To"},"description":"Console URL to return the browser to once the flow finishes. Must be under the configured console origin. When supplied, a failure to start the flow redirects here with an `error` query parameter instead of answering 400."}],"responses":{"303":{"description":"Authorization started. Redirects to the OAuth authorization endpoint discovered for this server.","headers":{"Location":{"description":"The provider's authorization endpoint, carrying the PKCE code challenge, the CSRF state, and the canonical resource identifier for this server.","schema":{"type":"string","format":"uri"}},"Set-Cookie":{"description":"Sets `oauth_state`, an HttpOnly Secure SameSite=Lax cookie holding the PKCE code verifier and CSRF state for ten minutes. The callback cannot complete without it, which is why this redirect has to be followed by a browser rather than by an HTTP client.","schema":{"type":"string"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Authorization is not required for this server"}}},"description":"The authorization flow could not be started: `server_url` is not a fetchable http(s) URL, the server publishes no protected-resource metadata naming an authorization server, `redirect_to` is outside the console origin, or discovery failed with no `redirect_to` to report the error to. A malformed `org_id` or `project_id` answers 400 as well, carrying a `MALFORMED_RESOURCE_IDENTIFIER` reason."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Authorizemcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_task_mcp_server permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_task_mcp_server"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"307":{"description":"Authorization could not be started, and `redirect_to` was supplied, so the failure is reported by redirecting back to it. The same failure answers 400 when `redirect_to` is omitted.","headers":{"Location":{"description":"The supplied `redirect_to`, with `error=oauth_authorization_failed`, `error_description` and `server_url` appended as query parameters.","schema":{"type":"string","format":"uri"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to start the authorization flow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Start the OAuth authorization flow for an MCP server that requires it.\n\nAnswers a redirect, so open it in a browser rather than following it with an HTTP client: the flow depends on the `oauth_state` cookie set alongside the redirect, and finishes at the callback below. Nothing is stored against a server here — the callback hands back an `auth_session_id` to pass to registration."}},"/org/{org_id}/project/{project_id}/task_mcp_server/discover":{"post":{"tags":["Task MCP Servers"],"summary":"Discover MCP Server Tools","operationId":"discoverMcpServerTools","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_task_mcp_server"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServerDiscoveryRequest"},"examples":{"by_url":{"summary":"Inspect a public server","value":{"server_url":"https://docs.rightbrain.ai/mcp"}}}}}},"responses":{"200":{"description":"The tools the server exposes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServerDiscoveryResponse"},"examples":{"Inspect a public server":{"summary":"Inspect a public server","value":{"server_url":"https://docs.rightbrain.ai/mcp","canonical_resource":"https://docs.rightbrain.ai/mcp","tools":[{"name":"searchDocs","description":"Search the documentation at https://docs.rightbrain.ai. Returns relevant doc passages with source URLs.","input_schema":{"type":"object","properties":{"query":{"type":"string","description":"The search query to run against the docs"}},"required":["query"],"additionalProperties":false,"$schema":"http://json-schema.org/draft-07/schema#"}}],"transport":"streamable_http"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Unable to discover tools: Failed to connect to MCP server at https://mcp.example.com/sse: ConnectError: [Errno -2] Name or service not known"}}},"description":"The MCP server could not be reached"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Discovermcpservertools"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_task_mcp_server permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_task_mcp_server"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid discovery request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid discovery request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to discover the server's tools","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Ask a remote MCP server what tools it exposes, without registering anything.\n\nCall this before registering tools so the names come from the server rather than a guess. Accepts the same authentication fields as registration, so a server behind an API key can be inspected before it is stored."}},"/org/{org_id}/project/{project_id}/task_mcp_server":{"post":{"tags":["Task MCP Servers"],"summary":"Create Task MCP Server","operationId":"createTaskMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_task_mcp_server"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpServerCreate"},"examples":{"streamable_http":{"summary":"Public server over streamable HTTP","value":{"name":"docs-search","description":"Rightbrain documentation search.","server_url":"https://docs.rightbrain.ai/mcp","transport":"streamable_http","enabled":true}}}}}},"responses":{"200":{"description":"The registered MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpServer"},"examples":{"Public server over streamable HTTP":{"summary":"Public server over streamable HTTP","value":{"name":"docs-search","description":"Rightbrain documentation search.","server_url":"https://docs.rightbrain.ai/mcp","enabled":true,"id":"019dddec-95cf-f920-e103-a11283fe0819","catalog_server_id":null,"catalog_server_slug":null,"canonical_resource":"https://docs.rightbrain.ai/mcp","transport":"streamable_http","auth_state":"none","auth_state_reason":null,"auth_type":"none","auth_strategy":null,"auth_header_name":null,"project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-29T09:15:00.000000Z","modified":"2026-07-29T09:15:00.000000Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server name already exists"}}},"description":"The registration was refused: this user already registered a server with that `name` in the project, `auth_session_id` does not name a live authorization session, or — only when `transport` is omitted — the server could not be probed to detect its transport."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskmcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_task_mcp_server permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_task_mcp_server"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid MCP server\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid MCP server","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"409":{"description":"Conflict - MCP server already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server already exists for this server URL"}}}},"503":{"description":"Redis is not configured for this deployment, so the `auth_session_id` cannot be read and the credentials cannot be attached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Redis is required when auth_session_id is provided"}}}},"500":{"description":"Internal Server Error - Failed to register the MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Register a remote MCP server in this project.\n\n`transport` is `streamable_http` or `sse`. Supplying it registers the server without ever contacting it; omit it and Rightbrain probes the server to detect the transport, which is the only part of registration that needs the server to be reachable. Either way the tools are not read here — register them against the server afterwards, which does contact it.\n\nAuthentication is optional: supply `api_key` with `api_key_strategy` and `api_key_header_name` for a key-based server, or complete the OAuth flow above and pass `auth_session_id`. Credentials are stored, never returned."},"get":{"tags":["Task MCP Servers"],"summary":"List Task MCP Servers","operationId":"listTaskMcpServers","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Page Limit"},"description":"Maximum number of MCP servers to return per page."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"The id of the last MCP server on the previous page. Omit for the first page; pass the `pagination.next_cursor` of the previous response to continue."}],"responses":{"200":{"description":"Successfully retrieved registered MCP servers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskMcpServer_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":100},"results":[{"name":"docs-search","description":"Rightbrain documentation search.","server_url":"https://docs.rightbrain.ai/mcp","enabled":true,"id":"019dddec-95cf-f920-e103-a11283fe0819","catalog_server_id":null,"catalog_server_slug":null,"canonical_resource":"https://docs.rightbrain.ai/mcp","transport":"streamable_http","auth_state":"none","auth_state_reason":null,"auth_type":"none","auth_strategy":null,"auth_header_name":null,"project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-29T09:15:00.000000Z","modified":"2026-07-29T09:15:00.000000Z"}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskmcpservers"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list the MCP servers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List the MCP servers registered in this project, newest first, including their current authorization state."}},"/org/{org_id}/project/{project_id}/task_mcp_server/catalog":{"get":{"tags":["Task MCP Servers"],"summary":"List MCP Server Catalog","operationId":"listTaskMcpServerCatalog","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Successfully retrieved the published catalog","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskMcpServerCatalogRead"},"title":"Response Listtaskmcpservercatalog"},"example":[{"id":"019dddec-c2a5-7f11-8e44-0b96d3a71c50","slug":"github","display_name":"GitHub","description":"Canonical catalog entry for the Rightbrain-supported GitHub MCP server.","canonical_resource":"https://api.githubcopilot.com/mcp","default_server_url":"https://api.githubcopilot.com/mcp/","default_transport":"streamable_http","auth_mode":"oauth_or_api_key","enabled":true},{"id":"019dddec-d3b6-7022-9f55-1ca7e4b82d61","slug":"slack","display_name":"Slack","description":"Canonical catalog entry for the Rightbrain-supported Slack MCP server.","canonical_resource":"https://slack.com/","default_server_url":"https://slack.com/mcp","default_transport":"streamable_http","auth_mode":"oauth","enabled":true}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskmcpservercatalog"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list the catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List the MCP servers Rightbrain publishes ready to register, so common servers do not have to be configured by hand.\n\nA bare array, not a paginated result set. `default_server_url` and `default_transport` are what to pass to registration; `auth_mode` says which of the two authentication routes the server accepts."}},"/org/{org_id}/project/{project_id}/task_mcp_server/catalog/{slug}":{"get":{"tags":["Task MCP Servers"],"summary":"Get MCP Server Catalog Entry","operationId":"getTaskMcpServerCatalog","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"},"description":"The canonical MCP server catalog slug"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Catalog entry details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpServerCatalogRead"},"example":{"id":"019dddec-c2a5-7f11-8e44-0b96d3a71c50","slug":"github","display_name":"GitHub","description":"Canonical catalog entry for the Rightbrain-supported GitHub MCP server.","canonical_resource":"https://api.githubcopilot.com/mcp","default_server_url":"https://api.githubcopilot.com/mcp/","default_transport":"streamable_http","auth_mode":"oauth_or_api_key","enabled":true}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskmcpservercatalog"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Catalog entry not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server catalog not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve the catalog entry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve one catalog entry by its slug, including the transport and authentication it expects."}},"/org/{org_id}/project/{project_id}/task_mcp_server/{task_mcp_server_id}":{"get":{"tags":["Task MCP Servers"],"summary":"Get Task MCP Server","operationId":"getTaskMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:view"]}],"parameters":[{"name":"task_mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"MCP server details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpServer"},"example":{"name":"docs-search","description":"Rightbrain documentation search.","server_url":"https://docs.rightbrain.ai/mcp","enabled":true,"id":"019dddec-95cf-f920-e103-a11283fe0819","catalog_server_id":null,"catalog_server_slug":null,"canonical_resource":"https://docs.rightbrain.ai/mcp","transport":"streamable_http","auth_state":"none","auth_state_reason":null,"auth_type":"none","auth_strategy":null,"auth_header_name":null,"project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-29T09:15:00.000000Z","modified":"2026-07-29T09:15:00.000000Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskmcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve the MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve one registered MCP server. Credentials are never returned — only whether authentication is configured and current."},"post":{"tags":["Task MCP Servers"],"summary":"Update Task MCP Server","operationId":"updateTaskMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:edit"]}],"parameters":[{"name":"task_mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpServerUpdate"},"examples":{"disable":{"summary":"Disable without deleting","value":{"description":"Rightbrain documentation search.","enabled":false}}}}}},"responses":{"200":{"description":"MCP server updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpServer"},"examples":{"Disable without deleting":{"summary":"Disable without deleting","value":{"name":"docs-search","description":"Rightbrain documentation search.","server_url":"https://docs.rightbrain.ai/mcp","enabled":false,"id":"019dddec-95cf-f920-e103-a11283fe0819","catalog_server_id":null,"catalog_server_slug":null,"canonical_resource":"https://docs.rightbrain.ai/mcp","transport":"streamable_http","auth_state":"none","auth_state_reason":null,"auth_type":"none","auth_strategy":null,"auth_header_name":null,"project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-29T09:15:00.000000Z","modified":"2026-07-29T09:20:00.000000Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server name already exists"}}},"description":"The update was refused: the new `name` is already used by another server the same user registered in this project, or `auth_session_id` does not name a live authorization session."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatetaskmcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid MCP server\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid MCP server","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server not found"}}}},"503":{"description":"Redis is not configured for this deployment, so the `auth_session_id` cannot be read and the credentials cannot be attached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Redis is required when auth_session_id is provided"}}}},"500":{"description":"Internal Server Error - Failed to update the MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update a registered server's metadata, credentials or enabled state.\n\n`server_url` and `transport` cannot be changed — register a new server instead, so existing tool registrations keep pointing at the endpoint they were checked against. Disabling keeps the registration but stops agents using its tools.\n\nThe remote server is not contacted, so this records what you send without re-checking it. Pass `auth_session_id` to attach credentials from a completed authorization flow, or `api_key` with `api_key_strategy` and `api_key_header_name` to replace a stored key; either moves `auth_state` to `connected` and clears `auth_state_reason`."},"delete":{"tags":["Task MCP Servers"],"summary":"Delete Task MCP Server","operationId":"deleteTaskMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:edit"]}],"parameters":[{"name":"task_mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"MCP server registration removed","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Deletetaskmcpserver"},"example":{"detail":"Task MCP server deleted successfully"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletetaskmcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server not found"}}}},"409":{"description":"The registration is still referenced by an active Task or TaskAgent. Remove those references before deleting the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server is still referenced by an active Task or TaskAgent. Remove active references before deleting this server."}}}},"500":{"description":"Internal Server Error - Failed to delete the MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Remove a server registration along with the tool registrations that depend on it. Tasks and TaskAgents referencing those tools stop being able to call them."}},"/org/{org_id}/project/{project_id}/task_mcp_server/{task_mcp_server_id}/refresh":{"post":{"tags":["Task MCP Servers"],"summary":"Refresh Task MCP Server","operationId":"refreshTaskMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:edit"]}],"parameters":[{"name":"task_mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"The refreshed MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpServer"},"example":{"name":"docs-search","description":"Rightbrain documentation search.","server_url":"https://docs.rightbrain.ai/mcp","enabled":true,"id":"019dddec-95cf-f920-e103-a11283fe0819","catalog_server_id":null,"catalog_server_slug":null,"canonical_resource":"https://docs.rightbrain.ai/mcp","transport":"streamable_http","auth_state":"none","auth_state_reason":null,"auth_type":"none","auth_strategy":null,"auth_header_name":null,"project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-29T09:15:00.000000Z","modified":"2026-07-29T09:15:00.000000Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Refreshtaskmcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server not found"}}}},"500":{"description":"Internal Server Error - Failed to refresh the MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Re-probe the server and update the registration's transport and authorization state.\n\nUse this after the remote server changes, or after its credentials expire: the registration is checked when it is created, not continuously.\n\nIt answers 200 either way. A server that cannot be reached, or that rejects the stored credentials, is reported by moving `auth_state` to `reauth_required` and setting `auth_state_reason` to `server_unreachable` or `credentials_rejected` — not by an error status. Read those two fields rather than the status code. Existing tool registrations are left alone; this does not remove a tool the server has stopped exposing."}},"/org/{org_id}/project/{project_id}/task_mcp_server/{task_mcp_server_id}/reauthorize":{"post":{"tags":["Task MCP Servers"],"summary":"Reauthorize Task MCP Server","operationId":"reauthorizeTaskMcpServer","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:edit"]}],"parameters":[{"name":"task_mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"redirect_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect To"},"description":"Console URL to return the browser to once the flow finishes. Must be under the configured console origin. When supplied, a failure to start the flow redirects here with an `error` query parameter instead of answering 400."}],"responses":{"303":{"description":"Authorization started. Redirects to the OAuth authorization endpoint discovered for this server.","headers":{"Location":{"description":"The provider's authorization endpoint, carrying the PKCE code challenge, the CSRF state, and the canonical resource identifier for this server.","schema":{"type":"string","format":"uri"}},"Set-Cookie":{"description":"Sets `oauth_state`, an HttpOnly Secure SameSite=Lax cookie holding the PKCE code verifier and CSRF state for ten minutes. The callback cannot complete without it, which is why this redirect has to be followed by a browser rather than by an HTTP client.","schema":{"type":"string"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"This server uses API key authentication. Update the API key via the update endpoint instead."}}},"description":"Reauthorization does not apply, or the flow could not be started: the server is configured with an API key rather than OAuth, its metadata no longer names an authorization server, `redirect_to` is outside the console origin, or discovery failed with no `redirect_to` to report the error to. A malformed path identifier answers 400 as well, carrying a `MALFORMED_RESOURCE_IDENTIFIER` reason."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Reauthorizetaskmcpserver"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"307":{"description":"Authorization could not be started, and `redirect_to` was supplied, so the failure is reported by redirecting back to it. The same failure answers 400 when `redirect_to` is omitted.","headers":{"Location":{"description":"The supplied `redirect_to`, with `error=oauth_authorization_failed`, `error_description` and `server_url` appended as query parameters.","schema":{"type":"string","format":"uri"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"mcp_server","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to reauthorize the MCP server","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Start the authorization flow again for a server whose credentials have expired or been revoked, keeping the existing registration and its tools.\n\nThis runs the same flow as the authorize endpoint and answers the same redirects: despite being a `POST` it does not return the server. The callback hands back an `auth_session_id` — pass it to the update endpoint to attach the refreshed credentials to this registration."}},"/org/{org_id}/project/{project_id}/task_mcp_server/{task_mcp_server_id}/iam/members":{"get":{"tags":["Task MCP Servers"],"summary":"IAM - List Task Mcp Server Members","description":"Lists all members that have been granted direct access to the task_mcp_server.","operationId":"task_mcp_server_iam_org_org_id_project_project_id_task_mcp_server_task_mcp_server_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:view","task_mcp_server:view_members"]}],"parameters":[{"name":"task_mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Task Mcp Server members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Mcp Server Iam Org Org Id Project Project Id Task Mcp Server Task Mcp Server Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task_mcp_server/{task_mcp_server_id}/iam/members/{member}":{"get":{"tags":["Task MCP Servers"],"summary":"IAM - Lookup Task Mcp Server Member","description":"Retrieve a specific member that has been granted direct access to the task_mcp_server.","operationId":"task_mcp_server_iam_org_org_id_project_project_id_task_mcp_server_task_mcp_server_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:view","task_mcp_server:view_members"]}],"parameters":[{"name":"task_mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Task Mcp Server member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Mcp Server Iam Org Org Id Project Project Id Task Mcp Server Task Mcp Server Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Task MCP Servers"],"summary":"IAM - Update Task Mcp Server Member","description":"Update the roles that a member holds on the task_mcp_server.","operationId":"task_mcp_server_iam_org_org_id_project_project_id_task_mcp_server_task_mcp_server_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:view"]}],"parameters":[{"name":"task_mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task_Mcp_ServerIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Task Mcp Server member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Task Mcp Server Iam Org Org Id Project Project Id Task Mcp Server Task Mcp Server Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Mcp Server Iam Org Org Id Project Project Id Task Mcp Server Task Mcp Server Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task_mcp_server/{task_mcp_server_id}/iam/test":{"post":{"tags":["Task MCP Servers"],"summary":"IAM - Test Task Mcp Server Permissions","description":"Test the permissions that the caller (or another subject) holds on the task_mcp_server.","operationId":"task_mcp_server_iam_org_org_id_project_project_id_task_mcp_server_task_mcp_server_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:view"]}],"parameters":[{"name":"task_mcp_server_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task_Mcp_ServerIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Task Mcp Server permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Task Mcp Server Iam Org Org Id Project Project Id Task Mcp Server Task Mcp Server Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Task Mcp Server Iam Org Org Id Project Project Id Task Mcp Server Task Mcp Server Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/task_mcp_tool":{"post":{"tags":["Task MCP Tools"],"summary":"Create Task MCP Tool","operationId":"createTaskMcpTool","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpToolCreate"},"examples":{"single":{"summary":"Register one tool","description":"`name` is the label shown to your agents; `tool_name` is the identifier on the remote server.","value":{"name":"Search Docs","description":"Searches the Rightbrain documentation.","tool_name":"searchDocs","task_mcp_server_id":"019dddec-95cf-f920-e103-a11283fe0819","enabled":true}}}}}},"responses":{"200":{"description":"MCP tool registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpTool"},"examples":{"Register one tool":{"summary":"Register one tool","value":{"id":"019dddec-a4f1-7c33-b820-6d5e0f14ab72","task_mcp_server_id":"019dddec-95cf-f920-e103-a11283fe0819","name":"Search Docs","description":"Searches the Rightbrain documentation.","tool_name":"searchDocs","tool_description":"Search the documentation at https://docs.rightbrain.ai. Returns relevant doc passages with source URLs.","tool_input_schema":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["query"],"properties":{"query":{"type":"string","description":"The search query to run against the docs"}},"additionalProperties":false},"safe_tool_name":"searchDocs","tool_timeout_seconds":30,"enabled":true,"created":"2026-07-29T09:16:00.000000Z","modified":"2026-07-29T09:16:00.000000Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Tool not found on remote server"}}},"description":"The MCP server does not expose a tool with that name, the tool is already registered for this server, or the server could not be reached. Unlike the bulk form, this one does not name the tool in the message."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskmcptool"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid MCP tool\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid MCP tool","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server not found"}}}},"500":{"description":"Internal Server Error - Failed to register the MCP tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Register one tool from an MCP server.\n\n`tool_name` must be a tool the remote server actually exposes — call `discoverMcpServerTools` first to list them. The API contacts the server while handling this request, so an unreachable server or an unknown tool answers 400 rather than creating anything."},"get":{"tags":["Task MCP Tools"],"summary":"List Task MCP Tools","operationId":"listTaskMcpTools","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_mcp_server_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Mcp Server Id"},"description":"Return only tools registered against this Task MCP server id. Omit to list the tools from every server in the project."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","default":100,"title":"Page Limit"},"description":"Maximum number of tools to return."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"Pagination cursor. Pass `pagination.next_cursor` from the previous page, which is the id of its last tool."}],"responses":{"200":{"description":"Successfully retrieved MCP tools","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskMcpTool_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":100},"results":[{"id":"019dddec-a4f1-7c33-b820-6d5e0f14ab72","task_mcp_server_id":"019dddec-95cf-f920-e103-a11283fe0819","name":"Search Docs","description":"Searches the Rightbrain documentation by keyword.","tool_name":"searchDocs","tool_description":"Search the documentation at https://docs.rightbrain.ai. Returns relevant doc passages with source URLs.","tool_input_schema":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["query"],"properties":{"query":{"type":"string","description":"The search query to run against the docs"}},"additionalProperties":false},"safe_tool_name":"searchDocs","tool_timeout_seconds":30,"enabled":false,"created":"2026-07-29T09:16:00.000000Z","modified":"2026-07-29T09:21:00.000000Z"}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskmcptools"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list the MCP tools","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List the MCP tools registered in this project, newest first. Filter to one server to see what it currently exposes to your agents."}},"/org/{org_id}/project/{project_id}/task_mcp_tool/bulk":{"post":{"tags":["Task MCP Tools"],"summary":"Create Task MCP Tools in Bulk","operationId":"createTaskMcpToolsBulk","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_server:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpToolBulkCreate"},"examples":{"several":{"summary":"Register the tools a server exposes","value":{"task_mcp_server_id":"019dddec-95cf-f920-e103-a11283fe0819","tools":[{"name":"Search Docs","tool_name":"searchDocs"}]}}}}}},"responses":{"200":{"description":"MCP tools registered in request order","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskMcpTool"},"title":"Response Createtaskmcptoolsbulk"},"examples":{"Register the tools a server exposes":{"summary":"Register the tools a server exposes","value":[{"id":"019dddec-b1c7-7e08-9a6d-2f3410db55e1","task_mcp_server_id":"019dddec-95cf-f920-e103-a11283fe0819","name":"Search Docs","description":null,"tool_name":"searchDocs","tool_description":"Search the documentation at https://docs.rightbrain.ai. Returns relevant doc passages with source URLs.","tool_input_schema":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["query"],"properties":{"query":{"type":"string","description":"The search query to run against the docs"}},"additionalProperties":false},"safe_tool_name":"searchDocs","tool_timeout_seconds":30,"enabled":true,"created":"2026-07-29T09:16:00.000000Z","modified":"2026-07-29T09:16:00.000000Z"}]}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Tool 'searchDocs' is already registered for server"}}},"description":"A tool is already registered for this server, is unknown to it, or the server could not be reached"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskmcptoolsbulk"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_mcp_server [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_server","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task MCP server\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP server belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid MCP tools\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid MCP tools","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP server not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP server not found"}}}},"500":{"description":"Internal Server Error - Failed to register the MCP tools","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Register several tools from one MCP server in a single request.\n\nEvery `tool_name` must exist on the remote server and must not already be registered for it. A repeat answers 400 naming the offending tool, so read the currently registered tools first if you are re-running this."}},"/org/{org_id}/project/{project_id}/task_mcp_tool/{task_mcp_tool_id}":{"get":{"tags":["Task MCP Tools"],"summary":"Get Task MCP Tool","operationId":"getTaskMcpTool","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_tool:view"]}],"parameters":[{"name":"task_mcp_tool_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Tool Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"MCP tool details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpTool"},"example":{"id":"019dddec-a4f1-7c33-b820-6d5e0f14ab72","task_mcp_server_id":"019dddec-95cf-f920-e103-a11283fe0819","name":"Search Docs","description":"Searches the Rightbrain documentation.","tool_name":"searchDocs","tool_description":"Search the documentation at https://docs.rightbrain.ai. Returns relevant doc passages with source URLs.","tool_input_schema":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["query"],"properties":{"query":{"type":"string","description":"The search query to run against the docs"}},"additionalProperties":false},"safe_tool_name":"searchDocs","tool_timeout_seconds":30,"enabled":true,"created":"2026-07-29T09:16:00.000000Z","modified":"2026-07-29T09:16:00.000000Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskmcptool"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_mcp_tool [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_tool","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task MCP tool\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP tool belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP tool not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve the MCP tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve one registered MCP tool."},"post":{"tags":["Task MCP Tools"],"summary":"Update Task MCP Tool","operationId":"updateTaskMcpTool","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_tool:edit"]}],"parameters":[{"name":"task_mcp_tool_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Tool Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpToolUpdate"},"examples":{"disable":{"summary":"Reword and disable","value":{"description":"Searches the Rightbrain documentation by keyword.","enabled":false}}}}}},"responses":{"200":{"description":"MCP tool updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskMcpTool"},"examples":{"Reword and disable":{"summary":"Reword and disable","value":{"id":"019dddec-a4f1-7c33-b820-6d5e0f14ab72","task_mcp_server_id":"019dddec-95cf-f920-e103-a11283fe0819","name":"Search Docs","description":"Searches the Rightbrain documentation by keyword.","tool_name":"searchDocs","tool_description":"Search the documentation at https://docs.rightbrain.ai. Returns relevant doc passages with source URLs.","tool_input_schema":{"type":"object","$schema":"http://json-schema.org/draft-07/schema#","required":["query"],"properties":{"query":{"type":"string","description":"The search query to run against the docs"}},"additionalProperties":false},"safe_tool_name":"searchDocs","tool_timeout_seconds":30,"enabled":false,"created":"2026-07-29T09:16:00.000000Z","modified":"2026-07-29T09:21:00.000000Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatetaskmcptool"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_mcp_tool [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_tool","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task MCP tool\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP tool belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid MCP tool\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid MCP tool","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP tool not found"}}}},"500":{"description":"Internal Server Error - Failed to update the MCP tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update a registered tool's label, description or enabled state.\n\n`tool_name` cannot be changed — register a different tool instead. Disabling keeps the registration but hides the tool from agents.\n\nThe remote server is not contacted, so the fields copied from it at registration — `tool_description`, `tool_input_schema`, `safe_tool_name` — come back unchanged. The stored `tool_input_schema` is re-checked, though, so a tool whose remote schema is no longer one Rightbrain can model answers 400 with an `Unsupported MCP tool input schema` message even when the fields you sent are fine; re-register the tool to pick the schema up again."},"delete":{"tags":["Task MCP Tools"],"summary":"Delete Task MCP Tool","operationId":"deleteTaskMcpTool","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_mcp_tool:edit"]}],"parameters":[{"name":"task_mcp_tool_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Mcp Tool Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"MCP tool registration removed","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"},"title":"Response Deletetaskmcptool"},"example":{"detail":"Task MCP tool deleted successfully"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletetaskmcptool"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_mcp_tool [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_mcp_tool","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task MCP tool\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task MCP tool belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"MCP tool not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP tool not found"}}}},"409":{"description":"The registration is still referenced by a task revision. Remove those references before deleting the tool.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task MCP tool is still referenced by task revisions. Remove MCP tool references from tasks before deleting."}}}},"500":{"description":"Internal Server Error - Failed to delete the MCP tool","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Remove a tool registration. Tasks and TaskAgents that reference it stop being able to call it, so check its dependants first."}},"/org/{org_id}/project/{project_id}/task/{task_id}/run/{task_run_id}/file/{file_name}":{"get":{"tags":["Tasks"],"summary":"Fetch a user submitted file (image or audio) for a given Task Run","operationId":"getTaskRunFile","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"task_run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["129c78d7-2e1f-4a77-adf3-68d69b0a3c71"],"title":"Task Run Id"},"description":"The specific Task Run to reference."},{"name":"file_name","in":"path","required":true,"schema":{"type":"string","examples":["93e38bb3-d94e-4a3e-8c80-9b8a1c1d7686.png","065d974b-86cf-4fff-a2ce-7a37a5eac037.mp3"],"title":"File Name"},"description":"The stored file name to fetch."},{"name":"inline","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Inline"},"description":"If true, serve file inline instead of as attachment"}],"responses":{"200":{"description":"File content returned successfully","content":{"application/json":{"schema":{}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"image/*":{"schema":{"type":"string","format":"binary"}},"audio/*":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}},"text/plain":{"schema":{"type":"string"},"example":"Docs probe fixture.\nThe quick brown fox jumps over the lazy dog.\n"}},"headers":{"Content-Disposition":{"description":"`attachment; filename=\"<stored_filename>\"`, or `inline; filename=\"<stored_filename>\"` when `inline=true`.","schema":{"type":"string"},"example":"attachment; filename=\"0633f35e-9957-4b60-8937-2838c3f825c4.txt\""},"Content-Type":{"description":"The stored file's own media type.","schema":{"type":"string"},"example":"text/plain; charset=utf-8"}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskrunfile"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Task run or file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"File not found"}}}}},"description":"Fetch an individual Task Run file.\n\nThis endpoint retrieves files associated with a task run, such as:\n- Input images or audio files submitted for processing\n- Output images, audio, PDFs, or CSV files generated by the task\n\nThe file is served with appropriate content type headers for inline viewing\nor download based on the `inline` parameter.\n\n`file_name` is the `stored_filename` from the run's `files` array, not the\nname the caller uploaded. Each entry there also carries a ready-made\n`download_url` for this endpoint.\n\nThe response carries the stored file's own content type — a `.txt` attachment\ncomes back as `text/plain`, not as an opaque byte stream — and a\n`Content-Disposition` header naming the stored file."}},"/org/{org_id}/project/{project_id}/task/{task_id}/run/{task_run_id}":{"get":{"tags":["Tasks"],"summary":"Fetch a Task Run","operationId":"getTaskRun","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"task_run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["129c78d7-2e1f-4a77-adf3-68d69b0a3c71"],"title":"Task Run Id"},"description":"The specific Task Run to reference."}],"responses":{"200":{"description":"Successfully retrieved task run information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskRun"},"examples":{"successful_run":{"summary":"Successful task run","value":{"id":"019f8a04-8e60-7b85-af37-6e9fb14d8fa4","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","model_name":"claude-sonnet-5","task_name":"Support Ticket Triage","output_modality":"json","response":{"category":"billing","priority":"high","summary":"Customer was double-charged for their Pro plan renewal and wants a refund."},"run_data":{"mcp_tool_calls":[],"integration_tool_calls":[],"submitted":{"subject":"Charged twice this month","body":"I was billed twice for my Pro subscription on the 3rd and the 5th. Please refund the duplicate charge.","plan":"Pro"}},"files":[],"is_error":false,"llm_retries":0,"used_fallback_model":false,"user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_basis":"direct_user","execution_surface":"task_api","execution_source_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","created":"2026-07-24T10:02:17Z","input_tokens":186,"output_tokens":42,"total_tokens":228,"input_processor_timing":0.00015282,"llm_call_timing":1.346,"charged_credits":"1.00","input_processor_charged_credits":"0.00"}},"with_fallback_model":{"summary":"Task run that used fallback model","value":{"id":"019f8a05-9f71-7c96-b048-7fa0c25f9ab5","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","model_name":"claude-sonnet-5","task_name":"Support Ticket Triage","output_modality":"json","response":{"category":"technical","priority":"urgent","summary":"API integration is returning 500 errors on all webhook deliveries since this morning."},"run_data":{"mcp_tool_calls":[],"integration_tool_calls":[],"submitted":{"subject":"Webhooks failing with 500","body":"All our webhook deliveries have been failing with a 500 error since 9am. This is blocking our production sync.","plan":"Enterprise"}},"files":[],"is_error":false,"llm_retries":1,"used_fallback_model":true,"primary_failure_reason":"Primary model rate limited (429)","fallback_llm_model_id":"019f6a01-0f4e-7d53-9a2c-6b7d8e9fa102","user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_basis":"trigger_owner","execution_surface":"webhook","execution_source_id":"019f8a03-7d5f-7084-9e26-5d8fa03c7e93","created":"2026-07-24T11:47:03Z","input_tokens":201,"output_tokens":47,"total_tokens":248,"input_processor_timing":0.0001671,"llm_call_timing":2.91,"charged_credits":"1.35","input_processor_charged_credits":"0.00"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid UUID format"}}},"description":"Bad Request - Invalid UUID format\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Gettaskrun"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request body\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request body","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_run [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_run","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve task run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve detailed information about a specific task run.\n\nTask runs provide a complete record of task executions, including:\n- Input parameters and configuration used\n- Execution status and timing information\n- Resource usage metrics (e.g., tokens consumed, credits charged)\n- Structured output and processing metadata\n- Error information if the run failed\n- Fallback model information if the primary model failed\n- Execution identity showing who caused the run and how it entered the platform\n\n**Response Fields:**\n\n*Timing Metrics:*\n- `input_processor_timing`: Time in seconds spent running input processors (e.g., `0.00015282`)\n- `llm_call_timing`: Time in seconds for the LLM API call (e.g., `1.346`)\n\n*Resource Usage:*\n- `charged_credits`: Credits charged for this execution as a string (e.g., `\"1.00\"`)\n- `input_tokens`: Number of input tokens processed\n- `output_tokens`: Number of output tokens generated\n- `total_tokens`: Combined token count\n\n*Retry & Fallback Information:*\n- `llm_retries`: Number of retry attempts made before success or failure\n- `used_fallback_model`: Boolean indicating if fallback model was used\n- `primary_failure_reason`: Reason why the primary model failed (if applicable)\n- `fallback_llm_model_id`: ID of the fallback model used (if applicable)\n\n*Input Data:*\n- `run_data.submitted`: The original input parameters as submitted\n\n*Execution Identity:*\n- `actor_user_id`: User whose authority caused the run\n- `actor_basis`: Why that user was trusted as the actor\n- `execution_surface`: Platform entry point used to start the run\n- `execution_source_id`: Surface-specific ID for correlating the run\n\nThis endpoint is useful for:\n- Monitoring task execution progress\n- Debugging failed runs and understanding failover behavior\n- Auditing task usage and performance\n- Retrieving task results\n- Analyzing reliability and fallback model usage\n\nErrors:\n- Returns 400 if the task run ID is not a valid UUID format\n- Returns 422 if the request body fails validation\n- Returns 404 if the task run is not found\n- Returns 403 if the user lacks permission to access the task run"}},"/org/{org_id}/project/{project_id}/task_run":{"get":{"tags":["Tasks"],"summary":"List Project Task Runs","operationId":"listProjectTaskRuns","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"task_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Id"},"description":"Filter to a specific task"},{"name":"task_revision_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Revision Id"},"description":"Filter to a specific task revision"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["success","error"],"type":"string"},{"type":"null"}],"title":"Status"},"description":"Filter by status (success or error)"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Start Date"},"description":"Start date for the listing (e.g., '2023-06-01', '24 hours ago', 'yesterday'). Defaults to 7 days before end_date or now."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"End Date"},"description":"End date for the listing (e.g., '2023-06-30', 'now', 'today'). Defaults to now."},{"name":"include_event_trigger_id","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Event Trigger Id"},"description":"If true, include event_trigger_id for each task run in results."}],"responses":{"200":{"description":"Paginated list of task runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskRun_"},"example":{"results":[{"id":"019f8a05-9f71-7c96-b048-7fa0c25f9ab5","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","model_name":"claude-sonnet-5","task_name":"Support Ticket Triage","output_modality":"json","response":{"category":"technical","priority":"urgent","summary":"API integration is returning 500 errors on all webhook deliveries since this morning."},"run_data":{"mcp_tool_calls":[],"integration_tool_calls":[],"submitted":{"subject":"Webhooks failing with 500","body":"All our webhook deliveries have been failing with a 500 error since 9am. This is blocking our production sync.","plan":"Enterprise"}},"files":[],"is_error":false,"llm_retries":1,"used_fallback_model":true,"primary_failure_reason":"Primary model rate limited (429)","fallback_llm_model_id":"019f6a01-0f4e-7d53-9a2c-6b7d8e9fa102","user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_basis":"trigger_owner","execution_surface":"webhook","execution_source_id":"019f8a03-7d5f-7084-9e26-5d8fa03c7e93","created":"2026-07-24T11:47:03Z","input_tokens":201,"output_tokens":47,"total_tokens":248,"input_processor_timing":0.0001671,"llm_call_timing":2.91,"charged_credits":"1.35","input_processor_charged_credits":"0.00"},{"id":"019f8a04-8e60-7b85-af37-6e9fb14d8fa4","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","task_revision_id":"019f8a01-4b3d-7e52-9c02-3b6d8f1a5c71","model_name":"claude-sonnet-5","task_name":"Support Ticket Triage","output_modality":"json","response":{"category":"billing","priority":"high","summary":"Customer was double-charged for their Pro plan renewal and wants a refund."},"run_data":{"mcp_tool_calls":[],"integration_tool_calls":[],"submitted":{"subject":"Charged twice this month","body":"I was billed twice for my Pro subscription on the 3rd and the 5th. Please refund the duplicate charge.","plan":"Pro"}},"files":[],"is_error":false,"llm_retries":0,"used_fallback_model":false,"user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","actor_basis":"direct_user","execution_surface":"task_api","execution_source_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","created":"2026-07-24T10:02:17Z","input_tokens":186,"output_tokens":42,"total_tokens":228,"input_processor_timing":0.00015282,"llm_call_timing":1.346,"charged_credits":"1.00","input_processor_charged_credits":"0.00"}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojecttaskruns"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"List all task runs across a project.\n\nReturns a paginated list of task runs for all tasks in the project.\nRuns belonging to soft-deleted tasks are excluded. Visibility is applied\nper task: users only see runs they would see on each task run list\n(owner_only / editors_and_owners / all_viewers). A page may contain\nfewer than page_limit results when visibility filters apply.\n\n**Filtering:** task_id, task_revision_id, status (success/error), start_date, end_date."}},"/org/{org_id}/project/{project_id}/task_run/recent_by_task":{"get":{"tags":["Tasks"],"summary":"List Project Recent Task Runs By Task","operationId":"listProjectRecentTaskRunsByTask","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"Maximum number of tasks to return per page."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"Pagination cursor for the next page of tasks."},{"name":"runs_per_task","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":30,"title":"Runs Per Task"},"description":"Maximum number of recent visible task runs to include for each task."}],"responses":{"200":{"description":"Paginated list of tasks with recent visible task runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskRecentRunsSummary_"},"example":{"results":[{"task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","task_name":"Support Ticket Triage","recent_runs":[{"id":"019f8a05-9f71-7c96-b048-7fa0c25f9ab5","status":"success","created":"2026-07-24T11:47:03+00:00"},{"id":"019f8a04-8e60-7b85-af37-6e9fb14d8fa4","status":"success","created":"2026-07-24T10:02:17+00:00"}]},{"task_id":"019f8a02-6c4e-7f63-8d15-4c7e9f2b6d82","task_name":"Invoice Line-Item Extractor","recent_runs":[]}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojectrecenttaskrunsbytask"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"List visible tasks in a project with recent visible task runs nested under each task.\n\nThis endpoint paginates tasks, not task runs. Each task includes up to `runs_per_task`\nrecent runs visible to the requesting user, ordered newest first. Tasks with no visible\nruns are still included with an empty `recent_runs` array.\n\nVisibility follows the same task-run visibility rules used by the project task-run list:\nusers may see all runs for some tasks, only their own runs for others, or no runs at all\nwhile still being able to view the task itself."}},"/org/{org_id}/project/{project_id}/task_run/timing_report":{"get":{"tags":["Tasks"],"summary":"Get Project Task Timing Report","operationId":"getProjectTaskTimingReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Id"},"description":"Filter to a specific task"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Start Date"},"description":"Report start timestamp"},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"End Date"},"description":"Report end timestamp"},{"name":"aggregation","in":"query","required":false,"schema":{"enum":["hour","day"],"type":"string","default":"hour","title":"Aggregation"},"description":"Time bucket granularity. Can be either 'hour' or 'day'."}],"responses":{"200":{"description":"Project Task timing report details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectTaskTimingReport"},"example":{"project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","date_range":{"start":"2026-07-24T08:00:00Z","end":"2026-07-24T11:00:00Z"},"aggregation":"hour","data":{"2026-07-24T08:00:00":{"avg_llm_call_timing":0.0,"total_task_runs":0},"2026-07-24T09:00:00":{"avg_llm_call_timing":0.0,"total_task_runs":0},"2026-07-24T10:00:00":{"avg_llm_call_timing":2.6357791689988517,"total_task_runs":1},"2026-07-24T11:00:00":{"avg_llm_call_timing":0.0,"total_task_runs":0}},"total_task_runs":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojecttasktimingreport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to build the timing report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Aggregate timing across the Task runs visible to the caller in this project.\n\nScope the report with `task_id`, `start_date` and `end_date`. `aggregation` selects the bucket granularity: `hour` (the default) covers the last 24 hours, `day` the last seven days.\n\n`data` contains every bucket in the window, including empty ones."}},"/org/{org_id}/project/{project_id}/task_run/usage_report":{"get":{"tags":["Tasks"],"summary":"Get Project Task Usage Report","operationId":"getProjectTaskUsageReport","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Id"},"description":"Filter to a specific task"},{"name":"aggregation","in":"query","required":false,"schema":{"enum":["day","week"],"type":"string","default":"day","title":"Aggregation"},"description":"Time bucket granularity. Can be either 'day' or 'week'."},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UsageReportStatus","default":"ALL"},"description":"Run outcome filter. Can be ALL, SUCCESS, or FAIL."}],"responses":{"200":{"description":"Project Task usage report details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectTaskUsageReport"},"example":{"project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","date_range":{"start":"2026-07-17T10:00:00.000000Z","end":"2026-07-24T10:00:00.000000Z"},"aggregation":"week","status":"ALL","data":{"2026-07-17T00:00:00":0,"2026-07-18T00:00:00":0,"2026-07-19T00:00:00":0,"2026-07-20T00:00:00":0,"2026-07-21T00:00:00":0,"2026-07-22T00:00:00":0,"2026-07-23T00:00:00":0,"2026-07-24T00:00:00":1},"total_runs":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getprojecttaskusagereport"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to build the usage report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Visible Task run counts over time for this project.\n\nScope the report with `task_id` and `status` (`ALL`, `SUCCESS` or `FAIL`). Unlike the timing report this endpoint has no `start_date`/`end_date`: the window is always relative to now, and `aggregation` chooses it — `day` (the default) returns the last 24 hours in hourly buckets, `week` returns the last seven days in daily buckets.\n\n`data` maps each bucket to a run count and contains every bucket in the window, including empty ones. `total_runs` is the sum across the window."}},"/org/{org_id}/project/{project_id}/task/{task_id}/eval/set":{"post":{"tags":["Task Evals"],"summary":"Create Eval Set","operationId":"createEvalSet","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"},"description":"The task ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSetCreate"},"example":{"name":"Ticket Triage baseline","description":"Two representative ticket-triage runs used as the reference baseline","task_run_ids":["019f8a04-8e60-7b85-af37-6e9fb14d8fa4","019f8a05-9f71-7c96-b048-7fa0c25f9ab5"]}}}},"responses":{"201":{"description":"Eval set created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSetResponse"},"example":{"id":"019fa4ec-98a8-9c34-e8f6-09f54481dd89","name":"Ticket Triage baseline","description":"Two representative ticket-triage runs used as the reference baseline","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","task_run_ids":["019f8a04-8e60-7b85-af37-6e9fb14d8fa4","019f8a05-9f71-7c96-b048-7fa0c25f9ab5"],"created":"2026-07-27T18:53:16.776040Z","modified":"2026-07-27T18:53:16.776040Z","created_by_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid eval set configuration"}}},"description":"Bad Request - Invalid eval set configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createevalset"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Create a reusable set of successful task runs for evals.\n\nThe set is later used as the reference baseline when comparing a candidate\nrevision's outputs against it (see Start Eval Run)."},"get":{"tags":["Task Evals"],"summary":"List Eval Sets","operationId":"listEvalSets","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"},"description":"The task ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"Paginated list of eval sets","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_EvalSetResponse_"},"example":{"results":[{"id":"019fa4ec-98a8-9c34-e8f6-09f54481dd89","name":"Ticket Triage baseline","description":"Two representative ticket-triage runs used as the reference baseline","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","task_run_ids":["019f8a04-8e60-7b85-af37-6e9fb14d8fa4","019f8a05-9f71-7c96-b048-7fa0c25f9ab5"],"created":"2026-07-27T18:53:16.776040Z","modified":"2026-07-27T18:53:16.776040Z","created_by_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01"}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listevalsets"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"List eval sets for the task."}},"/org/{org_id}/project/{project_id}/task/{task_id}/eval/set/{eval_set_id}":{"get":{"tags":["Task Evals"],"summary":"Get Eval Set","operationId":"getEvalSet","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"eval_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Eval Set Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"},"description":"The task ID"}],"responses":{"200":{"description":"Eval set retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSetResponse"},"example":{"id":"019fa4ec-98a8-9c34-e8f6-09f54481dd89","name":"Ticket Triage baseline","description":"Two representative ticket-triage runs used as the reference baseline","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","task_run_ids":["019f8a04-8e60-7b85-af37-6e9fb14d8fa4","019f8a05-9f71-7c96-b048-7fa0c25f9ab5"],"created":"2026-07-27T18:53:16.776040Z","modified":"2026-07-27T18:53:16.776040Z","created_by_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getevalset"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Eval set not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Eval set not found"}}}}},"description":"Get one eval set by ID."},"put":{"tags":["Task Evals"],"summary":"Update Eval Set","operationId":"updateEvalSet","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"eval_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Eval Set Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"},"description":"The task ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSetUpdate"},"example":{"name":"Ticket Triage baseline (v2)","description":"Updated reference set"}}}},"responses":{"200":{"description":"Eval set updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalSetResponse"},"example":{"id":"019fa4ec-98a8-9c34-e8f6-09f54481dd89","name":"Ticket Triage baseline (v2)","description":"Updated reference set","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","task_run_ids":["019f8a04-8e60-7b85-af37-6e9fb14d8fa4","019f8a05-9f71-7c96-b048-7fa0c25f9ab5"],"created":"2026-07-27T18:53:16.776040Z","modified":"2026-07-27T18:53:16.776040Z","created_by_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid eval set configuration"}}},"description":"Bad Request - Invalid eval set configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateevalset"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Eval set not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Eval set not found"}}}}},"description":"Update name, description, or run IDs on an eval set."},"delete":{"tags":["Task Evals"],"summary":"Delete Eval Set","operationId":"deleteEvalSet","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"eval_set_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Eval Set Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"},"description":"The task ID"}],"responses":{"204":{"description":"Eval set deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deleteevalset"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Eval set not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Eval set not found"}}}},"409":{"description":"Eval set is referenced by an active (pending or running) eval run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Eval set is referenced by an active eval run"}}}}},"description":"Delete an eval set if it is not referenced by active eval runs.\n\nAn eval run is \"active\" while its status is `pending` or `running`. Eval sets\nreferenced only by `completed` or `failed` runs can be deleted freely."}},"/org/{org_id}/project/{project_id}/task/{task_id}/eval/run":{"post":{"tags":["Task Evals"],"summary":"Start Eval Run","operationId":"createEvalRun","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:run_task"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"},"description":"The task ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalRunCreate"},"examples":{"from_eval_set":{"summary":"Judge a candidate revision against an eval set","value":{"eval_set_id":"019fa4ec-98a8-9c34-e8f6-09f54481dd89","candidate_revision_id":"019f8a06-aa82-7da7-b159-8bb1d36bab06"}},"from_last_n":{"summary":"Judge a candidate revision against the last N successful runs","value":{"last_n":10,"candidate_revision_id":"019f8a06-aa82-7da7-b159-8bb1d36bab06"}}}}}},"responses":{"201":{"description":"Eval run created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalRunResponse"},"examples":{"Judge a candidate revision against an eval set":{"summary":"Judge a candidate revision against an eval set","value":{"id":"019fa4ed-4fec-f5c1-e25a-7dc65ada66ca","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","candidate_revision_id":"019f8a06-aa82-7da7-b159-8bb1d36bab06","eval_set_id":"019fa4ec-98a8-9c34-e8f6-09f54481dd89","task_run_ids":["019f8a04-8e60-7b85-af37-6e9fb14d8fa4","019f8a05-9f71-7c96-b048-7fa0c25f9ab5"],"status":"completed","pass_count":2,"fail_count":0,"error_count":0,"started_at":"2026-07-27T18:54:04.584779Z","completed_at":"2026-07-27T18:54:11.458892Z","created":"2026-07-27T18:54:03.589524Z","modified":"2026-07-27T18:54:04.601868Z","created_by_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","pass_rate":1.0}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Candidate revision matches all reference runs. Choose a different candidate revision or use baseline runs from another revision."}}},"description":"Invalid eval run configuration"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createevalrun"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have run_task permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"run_task"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid request","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Create an eval run and dispatch background execution.\n\nAn eval run re-runs a candidate task revision against the same inputs as a\nset of reference (\"baseline\") task runs, then uses an LLM judge to compare\neach candidate output against its corresponding reference output.\n\n**Choosing the reference runs** (provide exactly one of):\n- `eval_set_id` — use the task runs stored in a previously created eval set\n- `task_run_ids` — use a specific, ad-hoc list of task run IDs (max 20)\n- `last_n` — use the task's `n` most recent successful runs (1-20)\n\n**Candidate revision:**\n- `candidate_revision_id` — the task revision to re-run and judge. Must differ\n  from the revision that produced the reference runs; the run is rejected\n  with a 400 if the candidate revision matches all reference runs.\n\n**Judge model:**\n- `judge_model_id` — optional; a platform default judge model is used if omitted.\n\nThe run starts in `pending` status and transitions to `running`, then\n`completed` or `failed`, as it executes in the background. Poll Get Eval Run\nfor the per-comparison verdicts once it completes."},"get":{"tags":["Task Evals"],"summary":"List Eval Runs","operationId":"listEvalRuns","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"},"description":"The task ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"Paginated list of eval runs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_EvalRunResponse_"},"example":{"results":[{"id":"019fa4ed-4fec-f5c1-e25a-7dc65ada66ca","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","candidate_revision_id":"019f8a06-aa82-7da7-b159-8bb1d36bab06","eval_set_id":"019fa4ec-98a8-9c34-e8f6-09f54481dd89","task_run_ids":["019f8a04-8e60-7b85-af37-6e9fb14d8fa4","019f8a05-9f71-7c96-b048-7fa0c25f9ab5"],"status":"completed","pass_count":2,"fail_count":0,"error_count":0,"started_at":"2026-07-27T18:54:04.584779Z","completed_at":"2026-07-27T18:54:11.458892Z","created":"2026-07-27T18:54:03.589524Z","modified":"2026-07-27T18:54:04.601868Z","created_by_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","pass_rate":1.0}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listevalruns"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"List eval runs for the task.\n\nReturns the summary shape (`EvalRunResponse`); it does not include the\nper-comparison judge results or aggregate metrics. Use Get Eval Run for those."}},"/org/{org_id}/project/{project_id}/task/{task_id}/eval/run/{eval_run_id}":{"get":{"tags":["Task Evals"],"summary":"Get Eval Run","operationId":"getEvalRun","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"eval_run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Eval Run Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Id"},"description":"The task ID"}],"responses":{"200":{"description":"Eval run detail retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalRunDetailResponse"},"example":{"id":"019fa4ed-4fec-f5c1-e25a-7dc65ada66ca","task_id":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60","project_id":"019f6b10-2e8a-7c91-9a3d-6e0f8b2c1d47","candidate_revision_id":"019f8a06-aa82-7da7-b159-8bb1d36bab06","eval_set_id":"019fa4ec-98a8-9c34-e8f6-09f54481dd89","task_run_ids":["019f8a04-8e60-7b85-af37-6e9fb14d8fa4","019f8a05-9f71-7c96-b048-7fa0c25f9ab5"],"status":"completed","pass_count":2,"fail_count":0,"error_count":0,"started_at":"2026-07-27T18:54:04.584779Z","completed_at":"2026-07-27T18:54:11.458892Z","created":"2026-07-27T18:54:03.589524Z","modified":"2026-07-27T18:54:04.601868Z","created_by_user_id":"019f6c10-1a2b-7c3d-8e4f-5a6b7c8d9e01","pass_rate":1.0,"judge_model":{"name":"claude-sonnet-5","provider":"Anthropic"},"metrics":{"token_cost":{"reference_avg":215.0,"candidate_avg":239.0,"delta_pct":11.16},"charged_credits":{"reference_avg":1.0,"candidate_avg":1.0,"delta_pct":0.0},"llm_call_timing":{"reference_avg":1.21,"candidate_avg":2.11,"delta_pct":74.35}},"results":[{"id":"019fa4ed-6bda-b54e-bc1d-d24d82d368e5","eval_run_id":"019fa4ed-4fec-f5c1-e25a-7dc65ada66ca","reference_run_id":"019f8a04-8e60-7b85-af37-6e9fb14d8fa4","candidate_run_id":"019fa4ed-5ffe-11e3-5898-7985979a6961","verdict":"pass","reasoning":"The candidate includes all fields from the reference (summary, category, priority) with identical values, plus an additional \"churn_risk\": false field. Since \"churn_risk\" is part of the expected output schema, its inclusion is appropriate rather than a hallucination.","judge_input_tokens":1026,"judge_output_tokens":232,"is_error":false,"created":"2026-07-27T18:54:10.912400Z","metrics":{"reference":{"total_tokens":215,"charged_credits":"1.00","llm_call_timing":1.37},"candidate":{"total_tokens":239,"charged_credits":"1.00","llm_call_timing":3.1}}},{"id":"019fa4ed-6da5-5941-4c3e-07c0831947b0","eval_run_id":"019fa4ed-4fec-f5c1-e25a-7dc65ada66ca","reference_run_id":"019f8a05-9f71-7c96-b048-7fa0c25f9ab5","candidate_run_id":"019fa4ed-585c-d185-be13-5659b377377e","verdict":"pass","reasoning":"The candidate output includes all fields from the reference (summary, category, priority) with identical values, and additionally includes \"churn_risk\": false. This is a schema-defined field the reference simply omitted, not a hallucination.","judge_input_tokens":1051,"judge_output_tokens":250,"is_error":false,"created":"2026-07-27T18:54:11.371402Z","metrics":{"reference":{"total_tokens":215,"charged_credits":"1.00","llm_call_timing":1.05},"candidate":{"total_tokens":239,"charged_credits":"1.00","llm_call_timing":1.11}}}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getevalrun"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Eval run not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Eval run not found"}}}}},"description":"Get eval run details with results and aggregate metrics.\n\nIn addition to the fields on `EvalRunResponse`, this returns:\n- `judge_model`: the model used to produce verdicts\n- `metrics`: reference vs. candidate averages (token cost, charged credits,\n  LLM call timing) with the percentage delta between them\n- `results`: one entry per reference/candidate run pair, each with the\n  judge's `verdict` (`pass`/`fail`), free-text `reasoning`, and per-pair\n  token and cost metrics\n\n`metrics` and `results` reflect the state at the time of the request; while\n`status` is `pending` or `running`, `results` may be a partial or empty list."}},"/org/{org_id}/project/{project_id}/trigger/webhook":{"post":{"tags":["Webhook Triggers"],"summary":"Create Webhook Trigger","operationId":"createWebhookTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTriggerCreate"},"examples":{"hmac":{"summary":"Inbound webhook with HMAC verification","description":"`payload_mapping` maps JSONPath expressions in the incoming body onto the target's input fields.","value":{"name":"helpdesk-inbound","description":"Fires the summariser when the helpdesk posts a ticket.","auth_method":"hmac_sha256","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","payload_mapping":{"text":"$.ticket.body"}}}}}}},"responses":{"201":{"description":"Webhook trigger created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTriggerWithSecret"},"examples":{"Inbound webhook with HMAC verification":{"summary":"Inbound webhook with HMAC verification","value":{"id":"019f8a25-4a1b-41ac-8f07-1b6c4d9e8032","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"webhook","name":"helpdesk-inbound","description":"Fires the summariser when the helpdesk posts a ticket.","status":"enabled","endpoint_id":"wh_k4Ttz1p-qXnR8","endpoint_url":"https://app.rightbrain.ai/api/v1/public/webhook/0190a234-9876-5432-10ab-cdef01234567/wh_k4Ttz1p-qXnR8","auth_method":"hmac_sha256","auth_config":null,"payload_mapping":{"text":"$.ticket.body"},"include_raw_payload":false,"idempotency_key_path":null,"idempotency_ttl_seconds":86400,"created":"2026-07-28T09:15:22.481203Z","modified":"2026-07-28T09:15:22.481203Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444","auth_secret":"whsec_EXAMPLEONLY-not-a-real-secret-AAAAAAAAAAAAA"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createwebhooktrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid webhook trigger\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid webhook trigger","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Target not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task not found"}}}},"500":{"description":"Internal Server Error - Failed to create the webhook trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a webhook trigger and return it together with its signing secret.\n\nThe secret is returned **only** on creation and when it is rotated, so store it when you receive it. `target_type` is `task` or `task_agent` and `target_id` is that resource's id."}},"/org/{org_id}/project/{project_id}/trigger":{"get":{"tags":["Webhook Triggers"],"summary":"List Triggers","operationId":"listTriggers","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Limit"},"description":"Maximum number of triggers to return."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"Return only triggers whose id is below this value. Pass the id of the last trigger from the previous page."},{"name":"trigger_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TriggerType"},{"type":"null"}],"title":"Trigger Type"},"description":"Return only triggers of this kind: `webhook`, `schedule` or `gmail_inbox`."},{"name":"target_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TriggerTargetType"},{"type":"null"}],"title":"Target Type"},"description":"Return only triggers whose target is a `task` or a `task_agent`. Required when `target_id` is supplied."},{"name":"target_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Id"},"description":"Return only triggers firing this Task or TaskAgent id. Supplying it without `target_type` answers 400."}],"responses":{"200":{"description":"Triggers in the project, of every kind","content":{"application/json":{"schema":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/WebhookTriggerListItem"},{"$ref":"#/components/schemas/ScheduleTriggerListItem"},{"$ref":"#/components/schemas/GmailInboxTriggerListItem"}],"discriminator":{"propertyName":"trigger_type","mapping":{"webhook":"#/components/schemas/WebhookTriggerListItem","schedule":"#/components/schemas/ScheduleTriggerListItem","gmail_inbox":"#/components/schemas/GmailInboxTriggerListItem"}}},"title":"Response Listtriggers"},"example":[{"id":"019f8a25-4a1b-41ac-8f07-1b6c4d9e8032","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"webhook","name":"helpdesk-inbound","description":"Fires the summariser when the helpdesk posts a ticket.","status":"enabled","created":"2026-07-28T09:15:22.481203Z","auth_method":"hmac_sha256"},{"id":"019f8a27-6b3d-41ac-9f18-2c7d5e0a9143","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"schedule","name":"nightly-summary","description":"Runs the summariser every night at 02:00 UTC.","status":"enabled","created":"2026-07-28T09:14:58.117402Z","cron_expression":"0 2 * * *","timezone":"UTC","next_run_at":"2026-07-29T02:00:00Z","expires_at":null}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtriggers"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list triggers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List every trigger in the project, of any kind.\n\nFilter with `trigger_type` (`webhook`, `schedule`, `gmail_inbox`) and `target_type` (`task`, `task_agent`)."}},"/org/{org_id}/project/{project_id}/trigger/webhook/{trigger_id}":{"get":{"tags":["Webhook Triggers"],"summary":"Get Webhook Trigger","operationId":"getWebhookTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"responses":{"200":{"description":"Webhook trigger details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTriggerResponse"},"example":{"id":"019f8a25-4a1b-41ac-8f07-1b6c4d9e8032","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"webhook","name":"helpdesk-inbound","description":"Fires the summariser when the helpdesk posts a ticket.","status":"enabled","endpoint_id":"wh_k4Ttz1p-qXnR8","endpoint_url":"https://app.rightbrain.ai/api/v1/public/webhook/0190a234-9876-5432-10ab-cdef01234567/wh_k4Ttz1p-qXnR8","auth_method":"hmac_sha256","auth_config":null,"payload_mapping":{"text":"$.ticket.body"},"include_raw_payload":false,"idempotency_key_path":null,"idempotency_ttl_seconds":86400,"created":"2026-07-28T09:15:22.481203Z","modified":"2026-07-28T09:15:22.481203Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getwebhooktrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Webhook trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve the webhook trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve a webhook trigger. The signing secret is not included — rotate it if it has been lost."},"post":{"tags":["Webhook Triggers"],"summary":"Update Webhook Trigger","operationId":"updateWebhookTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTriggerUpdate"},"examples":{"idempotency":{"summary":"Add idempotency handling","description":"`idempotency_key_path` deduplicates repeated deliveries within `idempotency_ttl_seconds`.","value":{"description":"Fires the summariser when the helpdesk posts a ticket.","include_raw_payload":true,"idempotency_key_path":"$.ticket.id","idempotency_ttl_seconds":3600}}}}}},"responses":{"200":{"description":"Webhook trigger updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTriggerResponse"},"examples":{"Add idempotency handling":{"summary":"Add idempotency handling","value":{"id":"019f8a25-4a1b-41ac-8f07-1b6c4d9e8032","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"webhook","name":"helpdesk-inbound","description":"Fires the summariser when the helpdesk posts a ticket.","status":"enabled","endpoint_id":"wh_k4Ttz1p-qXnR8","endpoint_url":"https://app.rightbrain.ai/api/v1/public/webhook/0190a234-9876-5432-10ab-cdef01234567/wh_k4Ttz1p-qXnR8","auth_method":"hmac_sha256","auth_config":null,"payload_mapping":{"text":"$.ticket.body"},"include_raw_payload":true,"idempotency_key_path":"$.ticket.id","idempotency_ttl_seconds":3600,"created":"2026-07-28T09:15:22.481203Z","modified":"2026-07-28T09:17:10.102304Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatewebhooktrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid webhook trigger\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid webhook trigger","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Webhook trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to update the webhook trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update a webhook trigger's metadata, delivery handling or status.\n\n`status` accepts `draft`, `disabled` or `enabled`. Supplying one or more fields advances `modified`; an empty body leaves it unchanged."},"delete":{"tags":["Webhook Triggers"],"summary":"Delete Webhook Trigger","operationId":"deleteWebhookTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"responses":{"204":{"description":"Webhook trigger deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletewebhooktrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Webhook trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to delete the webhook trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Delete a webhook trigger. Its endpoint stops accepting deliveries immediately."}},"/org/{org_id}/project/{project_id}/trigger/webhook/{trigger_id}/regenerate-endpoint":{"post":{"tags":["Webhook Triggers"],"summary":"Regenerate Webhook Endpoint","operationId":"regenerateWebhookEndpoint","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"responses":{"200":{"description":"Webhook trigger endpoint regenerated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTriggerResponse"},"example":{"id":"019f8a25-4a1b-41ac-8f07-1b6c4d9e8032","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"webhook","name":"helpdesk-inbound","description":"Fires the summariser when the helpdesk posts a ticket.","status":"enabled","endpoint_id":"wh_9dLm2Rb_tYqW4","endpoint_url":"https://app.rightbrain.ai/api/v1/public/webhook/0190a234-9876-5432-10ab-cdef01234567/wh_9dLm2Rb_tYqW4","auth_method":"hmac_sha256","auth_config":null,"payload_mapping":{"text":"$.ticket.body"},"include_raw_payload":true,"idempotency_key_path":"$.ticket.id","idempotency_ttl_seconds":3600,"created":"2026-07-28T09:15:22.481203Z","modified":"2026-07-28T09:18:31.214506Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Regeneratewebhookendpoint"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Webhook trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to regenerate the webhook endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Issue a new endpoint URL for the trigger. The previous URL stops accepting deliveries, so update the calling system before regenerating."}},"/org/{org_id}/project/{project_id}/trigger/webhook/{trigger_id}/rotate-secret":{"post":{"tags":["Webhook Triggers"],"summary":"Rotate Webhook Secret","operationId":"rotateWebhookSecret","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"responses":{"200":{"description":"Webhook trigger signing secret rotated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTriggerWithSecret"},"example":{"id":"019f8a25-4a1b-41ac-8f07-1b6c4d9e8032","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"webhook","name":"helpdesk-inbound","description":"Fires the summariser when the helpdesk posts a ticket.","status":"enabled","endpoint_id":"wh_9dLm2Rb_tYqW4","endpoint_url":"https://app.rightbrain.ai/api/v1/public/webhook/0190a234-9876-5432-10ab-cdef01234567/wh_9dLm2Rb_tYqW4","auth_method":"hmac_sha256","auth_config":null,"payload_mapping":{"text":"$.ticket.body"},"include_raw_payload":true,"idempotency_key_path":"$.ticket.id","idempotency_ttl_seconds":3600,"created":"2026-07-28T09:15:22.481203Z","modified":"2026-07-28T09:19:42.326708Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444","auth_secret":"whsec_EXAMPLEONLY-rotated-not-a-real-secret-BBBBB"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Rotatewebhooksecret"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Webhook trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to rotate the webhook secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Issue a new signing secret and return it. This is the only other response that contains the secret, and the previous one stops validating immediately."}},"/org/{org_id}/project/{project_id}/trigger/webhook/{trigger_id}/events":{"get":{"tags":["Webhook Triggers"],"summary":"List Webhook Trigger Events","operationId":"listWebhookTriggerEvents","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Limit"},"description":"Maximum number of events to return."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"Return only events whose id is below this value. Pass the id of the last event from the previous page."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"description":"Return only events in this delivery state: `received`, `processing`, `approval_required`, `completed`, `failed`, `duplicate` or `skipped`. Any other value answers 400."}],"responses":{"200":{"description":"Successfully retrieved delivery events for this webhook trigger","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/WebhookTriggerEventResponse"},"title":"Response Listwebhooktriggerevents"},"example":[{"id":"019f8a26-5b2c-42bd-9018-2c7d5e0a9143","webhook_trigger_id":"019f8a25-4a1b-41ac-8f07-1b6c4d9e8032","request_id":"req_8f2c41d9ab07","idempotency_key":null,"http_method":"POST","source_ip":"10.0.0.12","status":"completed","error_message":null,"error_code":null,"task_run_id":"0190b234-1111-2222-3333-444444444444","task_agent_run_id":null,"received_at":"2026-07-28T09:16:04.220118Z","completed_at":"2026-07-28T09:16:06.093664Z","response_status_code":200,"response_time_ms":1872}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listwebhooktriggerevents"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Webhook trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to list the trigger events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List the delivery events recorded for one webhook trigger, newest first. Each event records what arrived and what the trigger did with it."}},"/org/{org_id}/project/{project_id}/trigger/webhook/{trigger_id}/events/{event_id}":{"get":{"tags":["Webhook Triggers"],"summary":"Get Webhook Trigger Event","operationId":"getWebhookTriggerEvent","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Event Id"}}],"responses":{"200":{"description":"Webhook trigger delivery event details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTriggerEventDetailResponse"},"example":{"id":"019f8a26-5b2c-42bd-9018-2c7d5e0a9143","webhook_trigger_id":"019f8a25-4a1b-41ac-8f07-1b6c4d9e8032","request_id":"req_8f2c41d9ab07","idempotency_key":null,"http_method":"POST","source_ip":"10.0.0.12","status":"completed","error_message":null,"error_code":null,"task_run_id":"0190b234-1111-2222-3333-444444444444","task_agent_run_id":null,"received_at":"2026-07-28T09:16:04.220118Z","completed_at":"2026-07-28T09:16:06.093664Z","response_status_code":200,"response_time_ms":1872,"task_agent_id":null,"request_data":{"request_headers":{"host":"app.rightbrain.ai","x-real-ip":"203.0.113.42","user-agent":"Helpdesk-Webhook/1.0","traceparent":"00-4f1d8a2c6b3e5079d1c4a8f2e6b09d37-a1b2c3d4e5f60718-01","x-signature":"0000000000000000000000000000000000000000000000000000000000000000","content-type":"application/json","content-length":"91","accept-encoding":"identity","x-forwarded-for":"203.0.113.42","x-forwarded-host":"app.rightbrain.ai","x-forwarded-port":"443","x-forwarded-proto":"https","x-forwarded-prefix":"/api/v1","x-forwarded-server":"ingress-6b4d9c7f85-q2xkn"},"request_body":{"ticket":{"id":"TKT-4821","body":"Export keeps timing out after the latest release."}},"mapped_input":{"text":"Export keeps timing out after the latest release."}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getwebhooktriggerevent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Trigger event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Event not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve the trigger event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve one delivery event in full, including the payload as received and the run it started.\n\n`request_data.request_headers` reports every header the request arrived with, the signature header among them, so treat this response as sensitive. `source_ip` records the immediate peer — behind a proxy that is the ingress address, and the caller's own address appears in the forwarded headers."}},"/org/{org_id}/project/{project_id}/trigger/schedule":{"post":{"tags":["Schedule Triggers"],"summary":"Create Schedule Trigger","operationId":"createScheduleTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleTriggerCreate"},"examples":{"nightly":{"summary":"Nightly Task run","description":"`task_input` is sent to the target on every firing.","value":{"name":"nightly-summary","description":"Runs the summariser every night at 02:00 UTC.","cron_expression":"0 2 * * *","timezone":"UTC","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_input":{"text":"Yesterday's support tickets."}}}}}}},"responses":{"201":{"description":"Schedule trigger created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleTriggerResponse"},"examples":{"Nightly Task run":{"summary":"Nightly Task run","value":{"id":"019f8a27-6b3d-41ac-9f18-2c7d5e0a9143","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"schedule","name":"nightly-summary","description":"Runs the summariser every night at 02:00 UTC.","status":"enabled","cron_expression":"0 2 * * *","timezone":"UTC","task_input":{"text":"Yesterday's support tickets."},"next_run_at":"2026-07-29T02:00:00Z","last_run_at":null,"expires_at":null,"created":"2026-07-28T09:14:58.117402Z","modified":"2026-07-28T09:14:58.117402Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createscheduletrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid schedule trigger\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid schedule trigger","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Target not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Task not found"}}}},"500":{"description":"Internal Server Error - Failed to create the schedule trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a schedule trigger.\n\n`cron_expression` is evaluated in `timezone`, which defaults to UTC. `target_type` is `task` or `task_agent` and `target_id` is that resource's id. Set `expires_at` to stop firing after a date."}},"/org/{org_id}/project/{project_id}/trigger/schedule/events":{"get":{"tags":["Schedule Triggers"],"summary":"List Project Schedule Trigger Events","operationId":"listProjectScheduleTriggerEvents","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"description":"Return only events in this state: `received`, `processing`, `approval_required`, `completed`, `failed`, `duplicate` or `skipped`. Any other value answers 400."},{"name":"trigger_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TriggerType"},{"type":"null"}],"title":"Trigger Type"},"description":"Return only events from triggers of this kind: `webhook`, `schedule` or `gmail_inbox`."},{"name":"target_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TriggerTargetType"},{"type":"null"}],"title":"Target Type"},"description":"Return only events whose trigger targets a `task` or a `task_agent`. Required when `target_id` is supplied."},{"name":"target_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Id"},"description":"Return only events whose trigger fires this Task or TaskAgent id. Supplying it without `target_type` answers 400."}],"responses":{"200":{"description":"Successfully retrieved schedule trigger firing events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_ScheduleTriggerEventResponse_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":100},"results":[{"id":"019f8a28-7c4e-52bd-a029-3d8e6f1b0254","schedule_trigger_id":"019f8a27-6b3d-41ac-9f18-2c7d5e0a9143","scheduled_time":"2026-07-29T02:00:00Z","received_at":"2026-07-29T02:00:36.565278Z","processing_started_at":"2026-07-29T02:00:37.252854Z","completed_at":"2026-07-29T02:00:39.042946Z","status":"completed","error_message":null,"error_code":null,"task_run_id":"0190b234-1111-2222-3333-444444444444","task_agent_run_id":null}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojectscheduletriggerevents"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list the schedule trigger events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List firing events for every schedule trigger in the project, newest first.\n\nFilter with `trigger_type` and `target_type`."}},"/org/{org_id}/project/{project_id}/trigger/schedule/{trigger_id}":{"get":{"tags":["Schedule Triggers"],"summary":"Get Schedule Trigger","operationId":"getScheduleTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"responses":{"200":{"description":"Schedule trigger details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleTriggerResponse"},"example":{"id":"019f8a27-6b3d-41ac-9f18-2c7d5e0a9143","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"schedule","name":"nightly-summary","description":"Runs the summariser every night at 02:00 UTC.","status":"enabled","cron_expression":"0 2 * * *","timezone":"UTC","task_input":{"text":"Yesterday's support tickets."},"next_run_at":"2026-07-29T02:00:00Z","last_run_at":null,"expires_at":null,"created":"2026-07-28T09:14:58.117402Z","modified":"2026-07-28T09:14:58.117402Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getscheduletrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Schedule trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve the schedule trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve a schedule trigger, including its next firing time."},"post":{"tags":["Schedule Triggers"],"summary":"Update Schedule Trigger","operationId":"updateScheduleTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleTriggerUpdate"},"examples":{"reschedule":{"summary":"Reschedule and disable","value":{"description":"Runs the summariser every night at 03:00 UTC.","cron_expression":"0 3 * * *","status":"disabled"}}}}}},"responses":{"200":{"description":"Schedule trigger updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleTriggerResponse"},"examples":{"Reschedule and disable":{"summary":"Reschedule and disable","value":{"id":"019f8a27-6b3d-41ac-9f18-2c7d5e0a9143","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_agent_revision_id":null,"trigger_type":"schedule","name":"nightly-summary","description":"Runs the summariser every night at 03:00 UTC.","status":"disabled","cron_expression":"0 3 * * *","timezone":"UTC","task_input":{"text":"Yesterday's support tickets."},"next_run_at":"2026-07-29T02:00:00Z","last_run_at":null,"expires_at":null,"created":"2026-07-28T09:14:58.117402Z","modified":"2026-07-28T09:18:11.640925Z","created_by_user_id":"0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updatescheduletrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid schedule trigger\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid schedule trigger","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Schedule trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to update the schedule trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update a schedule trigger's cadence, payload or status.\n\n`status` accepts `draft`, `disabled` or `enabled` — a disabled trigger keeps its configuration but stops firing."},"delete":{"tags":["Schedule Triggers"],"summary":"Delete Schedule Trigger","operationId":"deleteScheduleTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"responses":{"204":{"description":"Schedule trigger deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletescheduletrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Schedule trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to delete the schedule trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Delete a schedule trigger. It stops firing immediately."}},"/org/{org_id}/project/{project_id}/trigger/schedule/{trigger_id}/events":{"get":{"tags":["Schedule Triggers"],"summary":"List Schedule Trigger Events","operationId":"listScheduleTriggerEvents","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Limit"},"description":"Maximum number of events to return."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"Return only events whose id is below this value. Pass the id of the last event from the previous page."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"description":"Return only events in this state: `received`, `processing`, `approval_required`, `completed`, `failed`, `duplicate` or `skipped`. Any other value answers 400."}],"responses":{"200":{"description":"Successfully retrieved firing events for this schedule trigger","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ScheduleTriggerEventResponse"},"title":"Response Listscheduletriggerevents"},"example":[{"id":"019f8a28-7c4e-52bd-a029-3d8e6f1b0254","schedule_trigger_id":"019f8a27-6b3d-41ac-9f18-2c7d5e0a9143","scheduled_time":"2026-07-29T02:00:00Z","received_at":"2026-07-29T02:00:36.565278Z","processing_started_at":"2026-07-29T02:00:37.252854Z","completed_at":"2026-07-29T02:00:39.042946Z","status":"completed","error_message":null,"error_code":null,"task_run_id":"0190b234-1111-2222-3333-444444444444","task_agent_run_id":null}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listscheduletriggerevents"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Schedule trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to list the schedule trigger events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List firing events for one schedule trigger, newest first. Each event records when the trigger fired and what the target returned."}},"/org/{org_id}/project/{project_id}/trigger/schedule/{trigger_id}/events/{event_id}":{"get":{"tags":["Schedule Triggers"],"summary":"Get Schedule Trigger Event","operationId":"getScheduleTriggerEvent","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Event Id"}}],"responses":{"200":{"description":"Schedule trigger firing event details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleTriggerEventDetailResponse"},"example":{"id":"019f8a28-7c4e-52bd-a029-3d8e6f1b0254","schedule_trigger_id":"019f8a27-6b3d-41ac-9f18-2c7d5e0a9143","scheduled_time":"2026-07-29T02:00:00Z","received_at":"2026-07-29T02:00:36.565278Z","processing_started_at":"2026-07-29T02:00:37.252854Z","completed_at":"2026-07-29T02:00:39.042946Z","status":"completed","error_message":null,"error_code":null,"task_run_id":"0190b234-1111-2222-3333-444444444444","task_agent_run_id":null,"task_input_snapshot":{"text":"Yesterday's support tickets."}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getscheduletriggerevent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Trigger event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Event not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve the trigger event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve one firing event in full, including the run it started and any failure recorded against it."}},"/org/{org_id}/project/{project_id}/trigger/gmail-inbox":{"post":{"tags":["Gmail Triggers"],"summary":"Create Gmail Inbox Trigger","operationId":"createGmailInboxTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GmailInboxTriggerCreate"},"examples":{"label_filter":{"summary":"Fire on a labelled message","description":"`payload_mapping` maps parts of the Gmail message onto the target's input fields.","value":{"name":"support-inbox","description":"Summarises messages landing in the support label.","project_integration_id":"019dd965-fd73-8c23-57f3-a06a470a4c2b","target_type":"task","target_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","label_ids":["Label_12"],"subject_contains":["invoice","receipt"],"payload_mapping":{"text":"$.message.snippet"}}}}}}},"responses":{"201":{"description":"Gmail inbox trigger created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GmailInboxTriggerResponse"},"examples":{"Fire on a labelled message":{"summary":"Fire on a labelled message","value":{"id":"019f8a05-6f65-7001-af6f-7fa142935051","target_type":"task_agent","target_id":"019f8a05-6f65-7002-af6f-7fa142935052","trigger_type":"gmail_inbox","name":"Support inbox intake","description":"Creates a support ticket task run for each new inbound email","status":"enabled","project_integration_id":"019f8a04-5e54-7007-9f5e-6e9031824047","integration_auth_principal_id":"019f8a04-5e54-7008-9f5e-6e9031824048","mailbox_watch_id":"019f8a05-6f65-7003-af6f-7fa142935053","email_address":"support@example.com","label_ids":["INBOX"],"sender_filters":[{"type":"domain","value":"example.com"}],"health_state":"healthy","watch_status":"active","watch_expiration_at":"2026-07-31T09:00:00Z","created":"2026-07-24T09:00:00Z","modified":"2026-07-24T09:00:00Z","created_by_user_id":"019f8a00-1a10-7003-8b1a-2a5c9d4e0003"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Creategmailinboxtrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid Gmail inbox trigger\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid Gmail inbox trigger","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Integration not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Integration not found"}}}},"409":{"description":"Gmail integration authorization is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"auth_required":{"summary":"Gmail authorization required","value":{"detail":{"code":"GMAIL_INTEGRATION_AUTH_REQUIRED","message":"Authorize Gmail before creating a Gmail inbox trigger."}}},"reauth_required":{"summary":"Gmail reauthorization required","value":{"detail":{"code":"GMAIL_INTEGRATION_REAUTH_REQUIRED","message":"Reauthorize Gmail before creating a Gmail inbox trigger."}}}}}}},"500":{"description":"Internal Server Error - Failed to create the Gmail inbox trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}},"503":{"description":"Gmail authorization is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"code":"GMAIL_INTEGRATION_AUTH_UNAVAILABLE","message":"Gmail authorization is not configured for this environment."}}}}}},"description":"Create a Gmail inbox trigger.\n\n`project_integration_id` must be an authorised Google integration in this project — authorise one first, because the trigger cannot create the grant. The filters narrow which messages fire it: `label_ids`, `sender_filters` and `subject_contains` are combined, so a message must satisfy all of the ones you set. `label_ids` and `subject_contains` are lists, and a message matches when any entry in the list matches."}},"/org/{org_id}/project/{project_id}/trigger/gmail-inbox/events":{"get":{"tags":["Gmail Triggers"],"summary":"List Project Gmail Trigger Events","operationId":"listProjectGmailInboxTriggerEvents","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"description":"Return only events in this state: `received`, `processing`, `approval_required`, `completed`, `failed`, `duplicate` or `skipped`. Any other value answers 400."},{"name":"target_type","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/TriggerTargetType"},{"type":"null"}],"title":"Target Type"},"description":"Return only events whose trigger targets a `task` or a `task_agent`. Required when `target_id` is supplied."},{"name":"target_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Id"},"description":"Return only events whose trigger fires this Task or TaskAgent id. Supplying it without `target_type` answers 400."}],"responses":{"200":{"description":"Successfully retrieved Gmail trigger events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_GmailTriggerEventResponse_"},"example":{"results":[{"id":"019f8a2a-9e60-74df-c24b-5f0a8b3d2476","gmail_inbox_trigger_id":"019f8a29-8d5f-63ce-b13a-4e9f7a2c1365","gmail_message_id":"18f2a4c9d1e0b7a3","history_id":"204815","email_address":"support@meridianfreight.co.uk","status":"completed","received_at":"2026-07-28T09:14:02Z"}],"pagination":{"has_next":false,"page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojectgmailinboxtriggerevents"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to list the Gmail trigger events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List delivery events for every Gmail inbox trigger in the project, newest first. Filter with `target_type`."}},"/org/{org_id}/project/{project_id}/trigger/gmail-inbox/{trigger_id}":{"get":{"tags":["Gmail Triggers"],"summary":"Get Gmail Inbox Trigger","operationId":"getGmailInboxTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"responses":{"200":{"description":"Gmail inbox trigger details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GmailInboxTriggerResponse"},"example":{"id":"019f8a05-6f65-7001-af6f-7fa142935051","target_type":"task_agent","target_id":"019f8a05-6f65-7002-af6f-7fa142935052","trigger_type":"gmail_inbox","name":"Support inbox intake","description":"Creates a support ticket task run for each new inbound email","status":"enabled","project_integration_id":"019f8a04-5e54-7007-9f5e-6e9031824047","integration_auth_principal_id":"019f8a04-5e54-7008-9f5e-6e9031824048","mailbox_watch_id":"019f8a05-6f65-7003-af6f-7fa142935053","email_address":"support@example.com","label_ids":["INBOX"],"sender_filters":[{"type":"domain","value":"example.com"}],"health_state":"healthy","watch_status":"active","watch_expiration_at":"2026-07-31T09:00:00Z","created":"2026-07-24T09:00:00Z","modified":"2026-07-24T09:00:00Z","created_by_user_id":"019f8a00-1a10-7003-8b1a-2a5c9d4e0003"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getgmailinboxtrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Gmail inbox trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve the Gmail inbox trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve a Gmail inbox trigger, including its filters and the integration it watches."},"post":{"tags":["Gmail Triggers"],"summary":"Update Gmail Inbox Trigger","operationId":"updateGmailInboxTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GmailInboxTriggerUpdate"},"examples":{"narrow_filters":{"summary":"Narrow to one sender and pause","value":{"description":"Summarises invoices only.","sender_filters":[{"type":"email","value":"billing@meridianfreight.co.uk"}],"status":"disabled"}}}}}},"responses":{"200":{"description":"Gmail inbox trigger updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GmailInboxTriggerResponse"},"examples":{"Narrow to one sender and pause":{"summary":"Narrow to one sender and pause","value":{"id":"019f8a05-6f65-7001-af6f-7fa142935051","target_type":"task_agent","target_id":"019f8a05-6f65-7002-af6f-7fa142935052","trigger_type":"gmail_inbox","name":"Support inbox intake","description":"Creates a support ticket task run for each new inbound email","status":"enabled","project_integration_id":"019f8a04-5e54-7007-9f5e-6e9031824047","integration_auth_principal_id":"019f8a04-5e54-7008-9f5e-6e9031824048","mailbox_watch_id":"019f8a05-6f65-7003-af6f-7fa142935053","email_address":"support@example.com","label_ids":["INBOX"],"sender_filters":[{"type":"domain","value":"example.com"}],"health_state":"healthy","watch_status":"active","watch_expiration_at":"2026-07-31T09:00:00Z","created":"2026-07-24T09:00:00Z","modified":"2026-07-24T09:00:00Z","created_by_user_id":"019f8a00-1a10-7003-8b1a-2a5c9d4e0003"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updategmailinboxtrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid Gmail inbox trigger\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid Gmail inbox trigger","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Gmail inbox trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to update the Gmail inbox trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update a Gmail inbox trigger's filters, metadata or status.\n\n`status` accepts `draft`, `disabled` or `enabled`. The integration it watches cannot be changed — create a trigger against the other integration instead."},"delete":{"tags":["Gmail Triggers"],"summary":"Delete Gmail Inbox Trigger","operationId":"deleteGmailInboxTrigger","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}}],"responses":{"204":{"description":"Gmail inbox trigger deleted successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deletegmailinboxtrigger"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Gmail inbox trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to delete the Gmail inbox trigger","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Delete a Gmail inbox trigger. Rightbrain stops watching the mailbox for it; the Google integration itself is left in place."}},"/org/{org_id}/project/{project_id}/trigger/gmail-inbox/{trigger_id}/events":{"get":{"tags":["Gmail Triggers"],"summary":"List Gmail Trigger Events","operationId":"listGmailInboxTriggerEvents","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Limit"},"description":"Maximum number of events to return."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"Return only events whose id is below this value. Pass the id of the last event from the previous page."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"description":"Return only events in this state: `received`, `processing`, `approval_required`, `completed`, `failed`, `duplicate` or `skipped`. Any other value answers 400."}],"responses":{"200":{"description":"Successfully retrieved events for this Gmail inbox trigger","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GmailTriggerEventResponse"},"title":"Response Listgmailinboxtriggerevents"},"example":[{"id":"019f8a2a-9e60-74df-c24b-5f0a8b3d2476","gmail_inbox_trigger_id":"019f8a29-8d5f-63ce-b13a-4e9f7a2c1365","gmail_message_id":"18f2a4c9d1e0b7a3","history_id":"204815","email_address":"support@meridianfreight.co.uk","status":"completed","received_at":"2026-07-28T09:14:02Z"}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listgmailinboxtriggerevents"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Gmail inbox trigger not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Trigger not found"}}}},"500":{"description":"Internal Server Error - Failed to list the Gmail trigger events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List delivery events for one Gmail inbox trigger, newest first. Each event records the message that arrived and what the trigger did with it.\n\nThis returns a plain array, not a paginated envelope — unlike the project-wide event list."}},"/org/{org_id}/project/{project_id}/trigger/gmail-inbox/{trigger_id}/events/{event_id}":{"get":{"tags":["Gmail Triggers"],"summary":"Get Gmail Trigger Event","operationId":"getGmailInboxTriggerEvent","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"trigger_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Trigger Id"}},{"name":"event_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Event Id"}}],"responses":{"200":{"description":"Gmail trigger event details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GmailTriggerEventDetailResponse"},"example":{"id":"019f8a2a-9e60-74df-c24b-5f0a8b3d2476","gmail_inbox_trigger_id":"019f8a29-8d5f-63ce-b13a-4e9f7a2c1365","gmail_message_id":"18f2a4c9d1e0b7a3","history_id":"204815","email_address":"support@meridianfreight.co.uk","status":"completed","received_at":"2026-07-28T09:14:02Z","mapped_input":null}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getgmailinboxtriggerevent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Trigger event not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Event not found"}}}},"500":{"description":"Internal Server Error - Failed to retrieve the trigger event","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve one delivery event in full, including the message metadata as received and the run it started.\n\n`GmailTriggerEventDetailResponse` is the list shape plus `mapped_input`: the input the trigger handed to its target, which is `null` unless the trigger declares a `payload_mapping`."}},"/org/{org_id}/project/{project_id}/slack/authorize":{"post":{"tags":["Slack"],"summary":"Start Slack OAuth","operationId":"authorizeSlackInstallation","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Slack OAuth authorize URL generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackOAuthStartResponse"},"example":{"authorize_url":"https://slack.com/oauth/v2/authorize?client_id=2650413579776.8329461075203&scope=app_mentions%3Aread%2Cchannels%3Ahistory%2Cchannels%3Aread%2Cchat%3Awrite%2Cchat%3Awrite.public%2Ccommands%2Cgroups%3Ahistory%2Cgroups%3Aread%2Cim%3Ahistory%2Cim%3Aread%2Cim%3Awrite%2Cusers%3Aread&redirect_uri=https%3A%2F%2Fapp.rightbrain.ai%2Fapi%2Fv1%2Fpublic%2Fslack%2Foauth%2Fcallback&state=eyJvcmdfaWQiOiIwMTkwYTIzNC01Njc4LTlhYmMtZGVmMC0xMjM0NTY3ODlhYmMiLCJwcm9qZWN0X2lkIjoiMDE5MGEyMzQtOTg3Ni01NDMyLTEwYWItY2RlZjAxMjM0NTY3IiwidHMiOjE3MDU0MTIwMDUsInVzZXJfaWQiOiIwMTkwYzIzNC0xMTExLTIyMjItMzMzMy00NDQ0NDQ0NDQ0NDQifQ.e6d2a272e812bf8be005486dce6e88eaf0d404c628ba87116dc89cf4baa53c6e"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Authorizeslackinstallation"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Generate a Slack OAuth authorize URL for connecting a workspace to this project.\n\nSend the user to `authorize_url`. It carries the app's client id, the scopes the Slack app requests, the platform's callback URL and a signed, time-limited `state` that pins the flow to this organization, project and user. The state expires ten minutes after it is issued. Answers 503 when Slack OAuth is not configured on this deployment."}},"/org/{org_id}/project/{project_id}/slack/installations":{"get":{"tags":["Slack"],"summary":"List Slack Installations","operationId":"listSlackInstallations","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"200":{"description":"Successfully retrieved Slack installations","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SlackInstallationResponse"},"title":"Response Listslackinstallations"},"example":[{"id":"019a5f0c-3b71-7d24-9e58-4c1d7a2b6e30","project_id":"0190a234-9876-5432-10ab-cdef01234567","team_id":"T024BE7LD","team_name":"Meridian Freight","bot_user_id":"U0KRQLJ9H","installed_by_user_id":"0190c234-1111-2222-3333-444444444444","status":"active","default_task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z"}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listslackinstallations"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"List Slack workspace installations configured for the project.\n\nRevoked installations are listed alongside active ones; read `status` to tell them apart. The workspace's bot token is never returned."}},"/org/{org_id}/project/{project_id}/slack/installations/{installation_id}":{"get":{"tags":["Slack"],"summary":"Get Slack Installation","operationId":"getSlackInstallation","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"installation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Installation Id"}}],"responses":{"200":{"description":"Slack installation details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackInstallationResponse"},"example":{"id":"019a5f0c-3b71-7d24-9e58-4c1d7a2b6e30","project_id":"0190a234-9876-5432-10ab-cdef01234567","team_id":"T024BE7LD","team_name":"Meridian Freight","bot_user_id":"U0KRQLJ9H","installed_by_user_id":"0190c234-1111-2222-3333-444444444444","status":"active","default_task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getslackinstallation"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Get the Slack installation details for a project workspace binding.\n\nAnswers 404 when the installation belongs to a different project, so an id from another project is indistinguishable from one that does not exist. The workspace's bot token is never returned."},"post":{"tags":["Slack"],"summary":"Update Slack Installation","operationId":"updateSlackInstallation","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"installation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Installation Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackInstallationUpdate"},"examples":{"revoke":{"summary":"Revoke the installation","value":{"status":"revoked"}}}}}},"responses":{"200":{"description":"Slack installation updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackInstallationResponse"},"examples":{"Revoke the installation":{"summary":"Revoke the installation","value":{"id":"019a5f0c-3b71-7d24-9e58-4c1d7a2b6e30","project_id":"0190a234-9876-5432-10ab-cdef01234567","team_id":"T024BE7LD","team_name":"Meridian Freight","bot_user_id":"U0KRQLJ9H","installed_by_user_id":"0190c234-1111-2222-3333-444444444444","status":"revoked","default_task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2024-01-16T13:33:25.247662Z","modified":"2024-02-04T09:12:41.882014Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateslackinstallation"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Update Slack installation defaults or lifecycle status.\n\nBoth fields are optional and only the ones present in the request are written. `default_task_agent_id` must name a TaskAgent in this project, or the request answers 400. Setting `status` to anything other than `active` also marks the linked integration's credential revoked and puts it into `reauth_required`, so reconnecting the workspace means running the OAuth flow again."},"delete":{"tags":["Slack"],"summary":"Delete Slack Installation","operationId":"deleteSlackInstallation","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"installation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Installation Id"}}],"responses":{"200":{"description":"Slack installation deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackDeleteResponse"},"example":{"ok":true}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deleteslackinstallation"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Soft-delete a Slack installation for the project.\n\nThe record is marked deleted rather than removed, and the linked integration's credential is marked disconnected. The Slack app itself is not uninstalled from the workspace — remove it in Slack as well if that is the intent."}},"/org/{org_id}/project/{project_id}/slack/installations/{installation_id}/channels":{"get":{"tags":["Slack"],"summary":"List Slack Channels","operationId":"listSlackChannels","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"installation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Installation Id"}}],"responses":{"200":{"description":"Successfully retrieved Slack channels","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SlackChannelResponse"},"title":"Response Listslackchannels"},"example":[{"id":"C024BE91L","name":"support-escalations","is_private":false,"is_archived":false,"is_member":true},{"id":"C7X2M4KQ8","name":"billing-queries","is_private":true,"is_archived":false}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listslackchannels"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"List public and private channels visible to the connected Slack installation.\n\nRead live from Slack with the installation's bot token, paging through every result rather than accepting a cursor, so this is a complete list and not a page. Nothing is filtered out here — check `is_archived` and `is_member` before routing to a channel. `is_member` is present only when Slack reported it. Answers 502 with Slack's own error string when Slack rejects the call."}},"/org/{org_id}/project/{project_id}/slack/installations/{installation_id}/channel-mappings":{"post":{"tags":["Slack"],"summary":"Create Slack Channel Mapping","operationId":"createSlackChannelMapping","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"installation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Installation Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackChannelMappingCreate"},"examples":{"by_channel_id":{"summary":"Map a channel by id","value":{"channel_id":"C024BE91L","channel_name":"support-escalations","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab"}},"by_channel_name":{"summary":"Map a channel by name","description":"With no `channel_id`, the name is resolved against Slack and the resolved id is stored.","value":{"channel_name":"billing-queries","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab"}}}}}},"responses":{"201":{"description":"Slack channel mapping created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackChannelMappingResponse"},"examples":{"by_channel_id":{"summary":"Map a channel by id","value":{"id":"019a5f0c-4c82-7d25-9f69-5d2e8b3c7f41","slack_installation_id":"019a5f0c-3b71-7d24-9e58-4c1d7a2b6e30","channel_id":"C024BE91L","channel_name":"support-escalations","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2024-01-16T14:02:18.114905Z","modified":"2024-01-16T14:02:18.114905Z"}},"by_channel_name":{"summary":"Map a channel by name","value":{"id":"019a5f0c-5d93-7d26-a07a-6e3f9c4d8052","slack_installation_id":"019a5f0c-3b71-7d24-9e58-4c1d7a2b6e30","channel_id":"C7X2M4KQ8","channel_name":"billing-queries","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2024-01-16T14:02:18.114905Z","modified":"2024-01-16T14:02:18.114905Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createslackchannelmapping"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Map a Slack channel to a TaskAgent for this installation.\n\nSupply either `channel_id` or `channel_name`; naming a channel resolves it to an id against Slack before the mapping is stored, and the response always carries the resolved `channel_id`. Name matching ignores case and a leading `#`. `task_agent_id` must name a TaskAgent in this project. Answers 400 when neither field is given, when the channel name cannot be resolved, when the TaskAgent is not in this project, or when this installation already maps that channel."},"get":{"tags":["Slack"],"summary":"List Slack Channel Mappings","operationId":"listSlackChannelMappings","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"installation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Installation Id"}}],"responses":{"200":{"description":"Successfully retrieved Slack channel mappings","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SlackChannelMappingResponse"},"title":"Response Listslackchannelmappings"},"example":[{"id":"019a5f0c-4c82-7d25-9f69-5d2e8b3c7f41","slack_installation_id":"019a5f0c-3b71-7d24-9e58-4c1d7a2b6e30","channel_id":"C024BE91L","channel_name":"support-escalations","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2024-01-16T14:02:18.114905Z","modified":"2024-01-16T14:02:18.114905Z"}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listslackchannelmappings"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"List Slack channel mappings for an installation.\n\nChannels with no mapping are handled by the installation's `default_task_agent_id`, so an empty list does not mean the workspace is inert."}},"/org/{org_id}/project/{project_id}/slack/installations/{installation_id}/channel-mappings/{mapping_id}":{"post":{"tags":["Slack"],"summary":"Update Slack Channel Mapping","operationId":"updateSlackChannelMapping","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"installation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Installation Id"}},{"name":"mapping_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mapping Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackChannelMappingUpdate"},"examples":{"reassign_agent":{"summary":"Reassign the channel to another TaskAgent","value":{"task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab"}}}}}},"responses":{"200":{"description":"Slack channel mapping updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackChannelMappingResponse"},"examples":{"Reassign the channel to another TaskAgent":{"summary":"Reassign the channel to another TaskAgent","value":{"id":"019a5f0c-4c82-7d25-9f69-5d2e8b3c7f41","slack_installation_id":"019a5f0c-3b71-7d24-9e58-4c1d7a2b6e30","channel_id":"C024BE91L","channel_name":"support-escalations","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","created":"2024-01-16T14:02:18.114905Z","modified":"2024-02-04T09:12:41.882014Z"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateslackchannelmapping"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Update the TaskAgent or display name for a Slack channel mapping.\n\nBoth fields are optional and only the ones present in the request are written, but `task_agent_id` may not be sent as null — omit it to leave the mapping's agent alone. A new `task_agent_id` must name a TaskAgent in this project, or the request answers 400. The mapped `channel_id` cannot be changed; delete the mapping and create another one instead."},"delete":{"tags":["Slack"],"summary":"Delete Slack Channel Mapping","operationId":"deleteSlackChannelMapping","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"installation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Installation Id"}},{"name":"mapping_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Mapping Id"}}],"responses":{"200":{"description":"Slack channel mapping deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlackDeleteResponse"},"example":{"ok":true}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deleteslackchannelmapping"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Delete a Slack channel to TaskAgent mapping.\n\nUnlike deleting an installation, this removes the row outright — mappings are not soft-deleted. The channel then falls back to the installation's `default_task_agent_id`, and is left unrouted only when the installation has none."}},"/org/{org_id}/project/{project_id}/integration/{integration_id}/teams/setup":{"get":{"tags":["Teams"],"summary":"Get Teams Integration Setup","operationId":"getTeamsIntegrationSetup","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Teams integration setup details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamsSetupResponse"},"example":{"teams_install_url":"https://teams.microsoft.com/l/app/8b1f4c62-9d3a-4e57-b8a1-0c72f5d6e394?tenantId=3f2504e0-4f89-41d3-9a0c-0305e82c3301","auth_state":"connected","auth_state_reason":null,"linked_installations":[{"id":"019a5f1d-6ea4-7d27-a18b-7f40ad5e9163","project_integration_id":"019a5f1d-7fb5-7d28-a29c-8051be6fa274","tenant_id":"3f2504e0-4f89-41d3-9a0c-0305e82c3301","team_id":"19:fd3f4e9a58a24b1e8c7d5f2a0b6c9e11@thread.tacv2","team_name":"Meridian Freight Operations","status":"active","created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:41:07.512883Z"}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getteamsintegrationsetup"}}},"description":"Forbidden"},"422":{"description":"Unprocessable Entity - Invalid integration ID\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_validation":{"summary":"Request validation failed","value":{"detail":[{"loc":["path","integration_id"],"msg":"Invalid integration ID","type":"value_error"}]}},"domain_validation":{"summary":"Domain precondition failed","value":{"detail":"Integration is not a Teams integration"}}}}}}},"description":"Return everything a Teams tab needs to finish connecting this integration: the deep link that installs the Rightbrain Teams app, the integration's authorization state, and the Teams installations already linked to it.\n\n`auth_state` is `connected` once an installation is linked and `reauth_required` otherwise, in which case `auth_state_reason` is `teams_installation_required`. Both are null until the integration has a default auth principal at all.\n\nAnswers 422 when `integration_id` names an integration that is not of type `teams`, and 503 when the Teams app id is not configured on this deployment."}},"/org/{org_id}/project/{project_id}/integration/{integration_id}/teams/tab-link":{"post":{"tags":["Teams"],"summary":"Link Teams Integration From Tab","operationId":"linkTeamsIntegrationFromTab","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:edit"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamsTabLinkRequest"},"examples":{"link_team":{"summary":"Link the signed-in team","description":"Only these three fields are read. `tenant_id` must match the token's `tid` claim.","value":{"teams_sso_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjY1NmVkZWJkLTcyOWItNDhjNS1hYjk3LTFiYjgzNDM3ZGY5MyJ9...","tenant_id":"3f2504e0-4f89-41d3-9a0c-0305e82c3301","team_id":"19:fd3f4e9a58a24b1e8c7d5f2a0b6c9e11@thread.tacv2"}}}}}},"responses":{"200":{"description":"Teams installation linked to the integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamsTabLinkResponse"},"examples":{"Link the signed-in team":{"summary":"Link the signed-in team","value":{"auth_state":"connected","auth_state_reason":null,"installation":{"teams_installation_id":"019a5f1d-6ea4-7d27-a18b-7f40ad5e9163","tenant_id":"3f2504e0-4f89-41d3-9a0c-0305e82c3301","team_id":"19:fd3f4e9a58a24b1e8c7d5f2a0b6c9e11@thread.tacv2","team_name":"Meridian Freight Operations","status":"active","created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:41:07.512883Z"}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Linkteamsintegrationfromtab"}}},"description":"Forbidden"},"422":{"description":"Unprocessable Entity - Invalid Teams tab link request\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_validation":{"summary":"Request validation failed","value":{"detail":[{"loc":["body"],"msg":"Invalid Teams tab link request","type":"value_error"}]}},"domain_validation":{"summary":"Domain precondition failed","value":{"detail":"Integration is not a Teams integration"}}}}}}},"description":"Link the Teams team the caller is signed in to with this integration, using the tab's SSO token as proof of tenant and team.\n\nThe bot must already have been added to that team: this operation links an installation the platform has *observed*, and never creates one. The Teams user calling it must also be the user who added the bot — there is no administrative override. On success the installation becomes `active`, the integration's default auth principal moves to `connected`, and the team's channels are synchronised; a channel-sync failure is logged and does not fail the request.\n\nAnswers 403 when the SSO token is invalid, expired, or issued for a different tenant than `tenant_id`. Answers 409 for the three link conflicts, which the response body distinguishes: `teams_installation_not_observed` when the bot has not been seen in that tenant and team, `teams_installation_already_linked` when that installation belongs to another integration, and `teams_installation_not_verified` or `teams_installation_user_mismatch` when the caller did not add the bot. Answers 422 when `integration_id` names an integration that is not of type `teams`, and 503 when the Teams bot is not configured on this deployment.\n\n`team_name`, `channel_id`, `channel_name` and `content_url` are accepted by the request model but are not read by this operation."}},"/org/{org_id}/project/{project_id}/integration/{integration_id}/teams/installations":{"get":{"tags":["Teams"],"summary":"List Teams Installations","operationId":"listTeamsIntegrationInstallations","security":[{"HTTPBearer":[]},{"HTTPBearer":["project_integration:view"]}],"parameters":[{"name":"integration_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Integration Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Successfully retrieved Teams installations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TeamsInstallationsResponse"},"example":{"auth_state":"connected","auth_state_reason":null,"installations":[{"id":"019a5f1d-6ea4-7d27-a18b-7f40ad5e9163","project_integration_id":"019a5f1d-7fb5-7d28-a29c-8051be6fa274","tenant_id":"3f2504e0-4f89-41d3-9a0c-0305e82c3301","team_id":"19:fd3f4e9a58a24b1e8c7d5f2a0b6c9e11@thread.tacv2","team_name":"Meridian Freight Operations","status":"active","created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:41:07.512883Z"}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listteamsintegrationinstallations"}}},"description":"Forbidden"},"422":{"description":"Unprocessable Entity - Invalid integration ID\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"request_validation":{"summary":"Request validation failed","value":{"detail":[{"loc":["path","integration_id"],"msg":"Invalid integration ID","type":"value_error"}]}},"domain_validation":{"summary":"Domain precondition failed","value":{"detail":"Integration is not a Teams integration"}}}}}}},"description":"List the Teams installations linked to this integration, with the integration's authorization state.\n\nReturns the same installations and the same `auth_state` and `auth_state_reason` as the setup operation, without the install deep link. `installations` is empty until a Teams team has been linked.\n\nAnswers 422 when `integration_id` names an integration that is not of type `teams`."}},"/org/{org_id}/project/{project_id}/task_share":{"get":{"tags":["Tasks"],"summary":"List Project Task Shares","description":"List all task shares across a project.\n\nReturns a paginated list of all task shares for tasks within the project.\nShares for soft-deleted tasks are excluded.\n\n**Filtering options:**\n- `active`: Filter by active status (true/false/omit for all)\n- `task_id`: Filter to shares for a specific task\n- `task_name`: Filter by task name (case-insensitive partial match)\n\n**Use cases:**\n- Audit all public shares in a project\n- Find active shares for a specific task\n- Review all shares created by the team","operationId":"listProjectTaskShares","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Active"},"description":"Filter by active status"},{"name":"task_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Id"},"description":"Filter by specific task ID"},{"name":"task_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Name"},"description":"Filter by task name (partial, case-insensitive)"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."}],"responses":{"200":{"description":"Paginated list of task shares","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskShare_"},"example":{"pagination":{"next_cursor":"01936abc-1234-5678-9abc-def012345678","has_next":true,"page_limit":100},"results":[{"id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe","task_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","user_id":"0190c234-1111-2222-3333-444444444444","task_name":"Awesome synonymiser","short_id":"tsiJP","share_url":"https://app.rightbrain.ai/s/tsiJP","title":"Awesome synonymiser","description":"When you've lost that thesaurus","views_count":15,"active":true,"created":"2025-11-06T11:27:50.140234Z","modified":"2025-11-06T11:27:50.140234Z","tags":[]}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojecttaskshares"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}}}},"/org/{org_id}/project/{project_id}/task/{task_id}/share":{"get":{"tags":["Tasks"],"summary":"List Task Shares","description":"List all share links for a task.\n\n**Note**: This endpoint returns a plain array of task shares, not a paginated response. All shares for the task are returned in a single request.\n\nReturns all active and inactive shares created for the specified task,\nordered by creation date (most recent first).\n\nEach share includes:\n- Share URL and short ID\n- Title and description\n- View count and active status\n- Expiration date (if set)\n- Creation and modification timestamps\n\nUse this endpoint to manage existing shares, check analytics, or deactivate old shares.","operationId":"listTaskShares","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."}],"responses":{"200":{"description":"List of task shares","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskShare"},"title":"Response Listtaskshares"},"example":[{"id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe","task_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","user_id":"0190c234-1111-2222-3333-444444444444","task_name":"Awesome synonymiser","short_id":"tsiJP","share_url":"https://app.rightbrain.ai/s/tsiJP","title":"Awesome synonymiser","description":"When you've lost that thesaurus","views_count":15,"active":true,"created":"2025-11-06T11:27:50.140234Z","modified":"2025-11-06T11:27:50.140234Z","tags":[]}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid task project mismatch"}}},"description":"Bad Request - Invalid task project mismatch\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskshares"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}}},"post":{"tags":["Tasks"],"summary":"Create Task Share","operationId":"createTaskShare","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskShareCreate"},"examples":{"time_limited":{"summary":"Time-limited share with custom title","value":{"title":"Support Ticket Triage (demo)","description":"Try the triage assistant on your own ticket text","expires_at":"2026-08-15T00:00:00Z"}},"never_expires":{"summary":"Share that never expires","value":{}},"specific_revision":{"summary":"Share a specific (non-active) revision","value":{"task_revision_id":"019f8a06-aa82-7da7-b159-8bb1d36bab06"}}}}}},"responses":{"200":{"description":"Share link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskShare"},"examples":{"Time-limited share with custom title":{"summary":"Time-limited share with custom title","value":{"id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe","task_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","user_id":"0190c234-1111-2222-3333-444444444444","task_name":"Awesome synonymiser","short_id":"tsiJP","share_url":"https://app.rightbrain.ai/s/tsiJP","views_count":0,"active":true,"created":"2025-11-06T11:27:50.140234Z","modified":"2025-11-06T11:27:50.140234Z","tags":[]}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid share settings"}}},"description":"Bad Request - Invalid share settings\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskshare"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Bad Request - Invalid unsupported RAG-backed task revision\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid unsupported RAG-backed task revision"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to create share link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a shareable link for a task.\n\nShare links allow external users to:\n- View task details without authentication\n- Run tasks with pre-configured inputs\n- Access task results\n\nConfigure share settings:\n- `title` / `description` to override what's shown on the public share page\n- `expires_at` — an absolute timestamp after which the share stops working (optional; omit for a share that never expires)\n- `task_revision_id` — share a specific revision instead of the task's current active revision (optional)\n- `task_run_id` — attach an existing task run as a worked example on the share page; must belong to the revision being shared (optional)\n- `custom_short_id` — a 3-5 character custom short link identifier (optional; a random one is generated if omitted). **Known issue**: as of this writing, passing `custom_short_id` causes a 500 error on the server; omit it until this is fixed.\n\nRAG-backed Task revisions are not currently shareable because their collections\nare project-local. MCP-backed Task revisions can be shared; clone copies or\nreuses MCP server and tool metadata without copying credentials."}},"/org/{org_id}/project/{project_id}/task/{task_id}/share/{share_id}":{"delete":{"tags":["Tasks"],"summary":"Revoke Task Share","description":"Revoke a task share by deactivating it.\n\nThis endpoint sets the share's active status to false, preventing further cloning.\nThe share link will no longer work for cloning, but the record is preserved for analytics.\n\nRevoking a share:\n- Sets active = false\n- Prevents cloning through the share link\n- Preserves share record and view count\n- Cannot be undone (create a new share instead)\n\nRequires edit permission on the task.","operationId":"revokeTaskShare","security":[{"HTTPBearer":[]},{"HTTPBearer":["task:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["01909843-3596-da54-4756-28af46917e74"],"title":"Task Id"},"description":"The specific Task to reference."},{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Share Id"},"description":"The ID of the task share to revoke"}],"responses":{"200":{"description":"Share successfully revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskShare"},"example":{"id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe","task_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","user_id":"0190c234-1111-2222-3333-444444444444","task_name":"Awesome synonymiser","short_id":"tsiJP","share_url":"https://app.rightbrain.ai/s/tsiJP","active":false,"views_count":15,"created":"2025-11-06T11:27:50.140234Z","modified":"2025-11-06T11:27:50.140234Z","tags":[]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid share task mismatch"}}},"description":"Bad Request - Invalid share task mismatch\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Revoketaskshare"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task share not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_share [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_share","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}}}},"/public/task_share/{short_id}":{"get":{"tags":["Tasks"],"summary":"Get Task Share","operationId":"getPublicTaskShare","parameters":[{"name":"short_id","in":"path","required":true,"description":"The unique share link identifier","schema":{"type":"string"},"example":"shr_1234567890abcdef"},{"name":"accept","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accept"}}],"responses":{"200":{"description":"Shared task share page or task details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskSharePublic"},"example":{"name":"Awesome synonymiser","description":"When you've lost that thesaurus","system_prompt":"You are a helpful assistant that creates concise summaries.","user_prompt":"Please summarize the following text: {text}","output_modality":"json","file_input_mode":"none","input_processors":[],"optimise_images":false,"llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model_name":"gpt-4-turbo"}},"text/html":{"schema":{"type":"string"},"example":"<!DOCTYPE html><html><body>Shared Task</body></html>"},"application/yaml":{"schema":{"type":"string"},"example":"name: Awesome synonymiser\ndescription: When you've lost that thesaurus\n"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Share link not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find share_link [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"share_link","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"410":{"description":"Share link has been revoked or expired\n\n**Common causes:**\n- The share link was revoked by its creator\n- The share link has passed its expiration date\n- The share link is no longer available\n\n**Resolution:** Request a new share link from the resource owner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Share link has been revoked or expired"}}}},"429":{"description":"Share link usage limit exceeded"},"500":{"description":"Internal Server Error - Failed to access shared task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Return a public task share page or task details.\n\nBrowser/default requests render a human-readable HTML share page. Clients\nthat send `Accept: application/json`, `application/yaml`, or `text/yaml`\nreceive the shared task details in that format instead.\n\nMay require additional authentication for sensitive tasks.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/task/clone/{short_id}":{"post":{"tags":["Tasks"],"summary":"Clone Shared Task","description":"Clone a shared task into a specified project.\n\nThis endpoint allows authenticated users to clone a shared task into their own project.\nThe cloned task will:\n- Copy all task settings (name, description, configuration)\n- Copy only the shared revision (not all revisions)\n- Automatically resolve name conflicts by appending (2), (3), etc.\n- Set cloned_from_task_revision_id to maintain a link to the original\n- Be set as active with 100% weight\n\nMCP-backed Task revisions are cloned by reusing a compatible target-project MCP\nserver or copying non-secret MCP server/tool metadata. MCP credentials and\nauth_config are never copied. Direct Task clone rejects auth-required MCP\ndependencies with 422 until this response model can represent setup-required\nclones.\n\nRequires create_task permission on the target project.","operationId":"cloneSharedTask","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_task"]}],"parameters":[{"name":"short_id","in":"path","required":true,"description":"The unique share link identifier","schema":{"type":"string"},"example":"tsiJP"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Task successfully cloned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"},"example":{"name":"Awesome synonymiser - clone","description":"When you've lost that thesaurus","enabled":true,"public":false,"exposed_to_agents":false,"output_modality":"json","task_run_visibility":"editors_and_owners","id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","project_id":"0190a234-9876-5432-10ab-cdef01234567","created":"2026-07-27T18:51:36.890278Z","modified":"2026-07-27T18:51:36.890278Z","revisions":[{"id":"019929cf-f316-196f-3bf9-118b22da0c3c","created":"2026-07-27T18:51:36.890278Z","modified":"2026-07-27T18:51:36.890278Z","system_prompt":"You are a helpful assistant that creates concise summaries.","user_prompt":"Please summarize the following text: {text}","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z"},"llm_config":{},"file_input_mode":"none","optimise_images":true,"test":false,"input_processors":[],"task_mcp_tool_ids":[],"integration_tool_ids":[],"active":true,"tags":[],"input_params":["text"]}],"access_token":"TASK_ACCESS_TOKEN_REDACTED","active_revisions":[{"task_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","weight":1.0}],"cloned_from_task_revision_id":"019929cf-f316-196f-3bf9-118b22da0c3c","tags":[],"shared_with_project":false}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"type":"validation_error","errors":[{"type":"inactive_share","message":"Task share is inactive and cannot be cloned"}]}}}},"description":"Task share is inactive and cannot be cloned"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Clonesharedtask","$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_task_mcp_server permission on project [0190a234-9876-5432-10ab-cdef01234567] (or it may not exist)","permissionCheckFailedError":{"resource":{"type":"project","id":"0190a234-9876-5432-10ab-cdef01234567"},"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"permission":"create_task_mcp_server"}}}}},"description":"Missing permission to clone an MCP dependency"},"422":{"description":"The Task share has an invalid MCP dependency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"type":"clone_dependency_error","message":"The Task share has an invalid MCP dependency"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Task share not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find task_share [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"task_share","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Failed to commit the cloned Task","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"type":"validation_error","errors":[{"type":"clone_commit_failed","message":"Failed to commit the cloned Task"}]}}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/public/task_share/{short_id}/file/{file_name}":{"get":{"tags":["Tasks"],"summary":"Download File from Shared Task","description":"Download a file from a task run example associated with a public task share.\n\nThis endpoint allows downloading files (images, documents, PDFs, CSVs, audio) from the example run\nattached to a shared task. Files are served with appropriate content types for inline viewing\nor download.\n\n**Supported file types:**\n- Input files: Images, documents uploaded during task execution\n- Output files: Generated images, audio files, PDFs, CSVs from task output\n\n**Access control:**\n- No authentication required (public endpoint)\n- Share must be active and not expired\n- File must be part of the share's example run\n\n**Error conditions:**\n- 404: Share not found or file not found\n- 410: Share has been revoked or expired","operationId":"getPublicTaskShareFile","parameters":[{"name":"short_id","in":"path","required":true,"description":"The unique share link identifier","schema":{"type":"string"},"example":"tsiJP"},{"name":"file_name","in":"path","required":true,"description":"The stored filename to download","schema":{"type":"string"},"example":"019a58ec-43b5-output.png"}],"responses":{"200":{"description":"File content returned successfully","content":{"application/json":{"schema":{}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}},"image/*":{"schema":{"type":"string","format":"binary"}},"audio/*":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}},"text/csv":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Share, example run, or file not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"share_not_found":{"summary":"No share with that short ID","value":{"detail":"Task share not found"}},"no_example_run":{"summary":"Share has no example run attached","value":{"detail":"No example run associated with this share"}},"file_not_found":{"summary":"The run holds no file by that name","value":{"detail":"File not found"}}}}}},"410":{"description":"The share has been revoked or has expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"revoked":{"summary":"Share revoked by its creator","value":{"detail":"This task share has been revoked and is no longer available"}},"expired":{"summary":"Share past its expiry date","value":{"detail":"This task share has expired"}}}}}}},"x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/task_agent_share":{"get":{"tags":["Task Agent Shares"],"summary":"List Project TaskAgent Shares","operationId":"listProjectTaskAgentShares","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"active","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Active"},"description":"Filter by active status"},{"name":"task_agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Id"},"description":"Filter by specific TaskAgent ID"},{"name":"task_agent_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Agent Name"},"description":"Filter by TaskAgent name (partial, case-insensitive)"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."},{"name":"page_limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."}],"responses":{"200":{"description":"Paginated list of TaskAgent shares","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_TaskAgentShare_"},"example":{"results":[{"id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe","project_id":"0190a234-9876-5432-10ab-cdef01234567","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","user_id":"0190c234-1111-2222-3333-444444444444","task_agent_name":"Support Agent","short_id":"supportagent","share_url":"https://app.rightbrain.ai/api/v1/public/task_agent_share/supportagent","title":"Support Agent","description":"Handles support triage and draft responses.","views_count":12,"active":true,"created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z","tags":[]}],"pagination":{"has_next":true,"next_cursor":"0190a234-8dc6-6d08-aea9-928fcecad8f2","page_limit":25}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listprojecttaskagentshares"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"List TaskAgent shares in a project.\n\nTaskAgent shares are public share records scoped to the requested project. The\nendpoint does not expose share-specific IAM."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/share":{"get":{"tags":["Task Agent Shares"],"summary":"List TaskAgent Shares","operationId":"listTaskAgentShares","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"}],"responses":{"200":{"description":"List of TaskAgent shares","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TaskAgentShare"},"title":"Response Listtaskagentshares"},"example":[{"id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe","project_id":"0190a234-9876-5432-10ab-cdef01234567","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","user_id":"0190c234-1111-2222-3333-444444444444","task_agent_name":"Support Agent","short_id":"supportagent","share_url":"https://app.rightbrain.ai/api/v1/public/task_agent_share/supportagent","title":"Support Agent","description":"Handles support triage and draft responses.","views_count":12,"active":true,"created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z","tags":[]}]}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid TaskAgent"}}},"description":"Bad Request - Invalid TaskAgent\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listtaskagentshares"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"TaskAgent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find taskagent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"taskagent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"List share links for a single TaskAgent.\n\nRequires `task_agent:view` on the parent TaskAgent. TaskAgentShare does not\nhave an independent IAM surface in v1."},"post":{"tags":["Task Agent Shares"],"summary":"Create TaskAgent Share","operationId":"createTaskAgentShare","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentShareCreate"},"example":{"task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","custom_short_id":"supportagent","title":"Support Agent","description":"Handles support triage and draft responses."}}}},"responses":{"201":{"description":"TaskAgent share created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentShare"},"example":{"id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe","project_id":"0190a234-9876-5432-10ab-cdef01234567","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","user_id":"0190c234-1111-2222-3333-444444444444","task_agent_name":"Support Agent","short_id":"supportagent","share_url":"https://app.rightbrain.ai/api/v1/public/task_agent_share/supportagent","title":"Support Agent","description":"Handles support triage and draft responses.","views_count":12,"active":true,"created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z","tags":[]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid invalid revision or short ID"}}},"description":"Bad Request - Invalid invalid revision or short ID\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createtaskagentshare"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"TaskAgent revision contains an unsupported RAG-backed or deleted Task-tool dependency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"TaskAgent not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find taskagent [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"taskagent","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to generate a unique short ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Unable to generate a unique TaskAgent share short ID"}}}}},"description":"Create a public share link for a TaskAgent revision.\n\nRequires `task_agent:edit` on the parent TaskAgent. If\n`task_agent_revision_id` is omitted, the active revision is shared. Custom short\nIDs must be unique and match the schema constraints; generated short IDs use\nhigh-entropy random characters.\n\nTaskAgent shares cannot include Task-tool revisions backed by RAG collections,\nincluding disabled Task-tool attachments, because those collections are\nproject-local and are not cloned. TaskAgent shares also cannot include deleted\nTask-tool dependencies."}},"/org/{org_id}/project/{project_id}/task-agent/{task_agent_id}/share/{share_id}":{"delete":{"tags":["Task Agent Shares"],"summary":"Revoke TaskAgent Share","operationId":"revokeTaskAgentShare","security":[{"HTTPBearer":[]},{"HTTPBearer":["task_agent:edit"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"},{"name":"task_agent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":"The task agent ID"},{"name":"share_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Share Id"},"description":"TaskAgent share ID"}],"responses":{"200":{"description":"TaskAgent share revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentShare"},"example":{"id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe","project_id":"0190a234-9876-5432-10ab-cdef01234567","task_agent_id":"019df849-e106-3301-5894-291b4c9c6cab","task_agent_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef4","user_id":"0190c234-1111-2222-3333-444444444444","task_agent_name":"Support Agent","short_id":"supportagent","share_url":"https://app.rightbrain.ai/api/v1/public/task_agent_share/supportagent","title":"Support Agent","description":"Handles support triage and draft responses.","views_count":12,"active":false,"created":"2026-05-05T10:15:00Z","modified":"2026-05-05T10:15:00Z","tags":[]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid share task agent mismatch"}}},"description":"Bad Request - Invalid share task agent mismatch\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Revoketaskagentshare"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have edit permission on task_agent [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"task_agent","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"edit"}}}}},"description":"Forbidden - Insufficient permissions for task_agent\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The task_agent belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"TaskAgent share not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find taskagent_share [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"taskagent_share","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Revoke a TaskAgent share by setting `active` to false.\n\nRequires `task_agent:edit` on the parent TaskAgent. The share record is\npreserved for management views and analytics."}},"/public/task_agent_share/{short_id}":{"get":{"tags":["Task Agent Shares"],"summary":"Get Public TaskAgent Share","operationId":"getPublicTaskAgentShare","parameters":[{"name":"short_id","in":"path","required":true,"schema":{"type":"string","title":"Short Id"},"description":"TaskAgent share short ID"},{"name":"accept","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accept"}}],"responses":{"200":{"description":"Public TaskAgent share page or data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentSharePublic"},"example":{"short_id":"supportagent","title":"Support Agent","description":"Handles support triage and draft responses.","views_count":12,"created":"2026-05-05T10:15:00Z","agent":{"name":"Support Agent","description":"Handles support triage and draft responses."},"revision":{"instruction":"Triage the customer request and draft a concise response.","mode":"agentic","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","name":"gpt-4o","alias":"GPT 4o","provider":"OpenAI","vendor":"openai"},"task_tools":[{"task_name":"Customer Support Analyzer","task_description":"Classifies sentiment and issue category.","enabled":true,"order":0,"is_output_formatter":false,"task_revision":{"system_prompt":"You are a support triage assistant.","user_prompt":"Customer message: {message}","output_format":{"sentiment":{"type":"str","description":"sentiment"},"category":{"type":"str","description":"issue category"}},"output_modality":"json","file_input_mode":"none","input_processors":[]}}],"skills":[],"mcp_servers":[],"integrations":[],"registered_tools":[]}}},"text/html":{"schema":{"type":"string"},"example":"<!DOCTYPE html><html><body>Shared TaskAgent</body></html>"},"application/yaml":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"TaskAgent share not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find taskagent_share [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"taskagent_share","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"410":{"description":"TaskAgent share has been revoked or has expired"}},"description":"Return a public TaskAgent share page or sanitized public data.\n\nBrowser/default requests render a human-readable HTML share page. Clients that\nsend `Accept: application/json`, `application/yaml`, or `text/yaml` receive\nsanitized public data.\n\nThe public DTO is allowlisted. It intentionally includes operational\nconfiguration needed to understand the shared agent, such as input processor\nconfiguration and tool names, but redacts credentials, tokens, auth configs,\nciphertext, connected user IDs, source-project provenance, tags, runs, files,\nand sessions. Public paths remain present in OpenAPI for schema generation but\nare marked `x-fern-ignore` by the `/public/*` OpenAPI configuration.","x-fern-ignore":true}},"/org/{org_id}/project/{project_id}/task-agent/clone/{short_id}":{"post":{"tags":["Task Agent Shares"],"summary":"Clone Shared TaskAgent","operationId":"cloneSharedTaskAgent","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_task_agent"]}],"parameters":[{"name":"short_id","in":"path","required":true,"schema":{"type":"string","title":"Short Id"},"description":"TaskAgent share short ID"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"},"description":"The organization ID"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"},"description":"The project ID"}],"responses":{"201":{"description":"TaskAgent share cloned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskAgentCloneResult"},"example":{"task_agent":{"id":"019df849-e117-2017-a34d-e056c24d33f7","name":"Support Agent copy","active_revision":{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_id":"019df849-e117-2017-a34d-e056c24d33f7","created":"2026-07-20T14:32:00Z","modified":"2026-07-20T14:32:00Z"},"revisions":[{"id":"019df849-e12a-b57e-62d4-0e5875e91ef4","task_agent_id":"019df849-e117-2017-a34d-e056c24d33f7","description":"Handles support triage and draft responses.","instruction":"Triage the customer request and draft a concise response.","mode":"agentic","llm_model_id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model":{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z"},"fallback_llm_model_id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","fallback_llm_model":{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z"},"task_tools":[{"id":"019df849-e12a-b57e-62d4-0e5875e91ef7","task_id":"019df849-e12a-b57e-62d4-0e5875e91ef8","task_revision_id":"019df849-e12a-b57e-62d4-0e5875e91ef9","revision_strategy":"pinned","task_name":"Customer Support Analyzer","order":0,"enabled":true,"is_output_formatter":true,"action_mode":"auto_run","rejection_behavior":"end_run"}],"integrations":[],"skills":[],"mcp_servers":[],"registered_tools":[],"tags":[],"active":true,"created":"2026-07-20T14:32:00Z","modified":"2026-07-20T14:32:00Z"}],"task_agent_run_visibility":"editors_and_owners","shared_with_project":false,"is_deleted":false,"created":"2026-07-20T14:32:00Z","modified":"2026-07-20T14:32:00Z"},"runnable":false,"dependency_report":[{"kind":"integration","source_id":"019df849-e12a-b57e-62d4-0e5875e91ef5","target_id":"019df849-e12a-b57e-62d4-0e5875e91ef6","name":"google_sheets","action":"cloned","status":"setup_required","reason":"integration_auth_required","message":"Integration metadata was copied without credentials and requires reauthorization."},{"kind":"registered_tool","name":"rfp-response-analyzer","action":"reused","status":"ready"}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Clonesharedtaskagent"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_task_agent permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_task_agent"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"The shared TaskAgent cannot be cloned or has unsupported dependencies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Skill capability dependency 'sheet-search' could not be resolved: integration_remap_unavailable"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"TaskAgent share not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find taskagent_share [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"taskagent_share","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"410":{"description":"TaskAgent share has been revoked or has expired"}},"description":"Clone a shared TaskAgent revision into the target project.\n\nRequires `project:create_task_agent` on the target project. The clone path\ncommits new database rows before writing IAM relationships, never copies source\nIAM relationships, and conditionally checks dependency-specific create\npermissions before cloning Tasks, Skills, integrations, or MCP servers.\n\nThe response includes a dependency report. `runnable=false` means at least one\ndependency requires setup, such as reauthorizing a copied integration or MCP\nserver. MCP-backed Task-tool revisions are cloned by reusing compatible\ntarget-project MCP server/tool metadata or copying non-secret metadata. MCP\ncredentials and auth_config are never copied. Auth-required Task-tool MCP\ndependencies may clone successfully with `runnable=false` and setup-required\ndependency report entries."}},"/org/{org_id}/project/{project_id}/model":{"get":{"tags":["Listings"],"summary":"List Available LLM Models","description":"Retrieve a list of all available Large Language Models (LLMs) that can be used in Tasks.\n\n**Note**: This endpoint returns a plain array of models, not a paginated response. All available models are returned in a single request.\n\nBy default, only active models available to the project are returned. Use `include_retired=true` to include retired models and `include_excluded=true` to include models excluded by organization or project rules.\n\nOptionally filter by vision (input) using one or more `vision` query parameters (e.g. `?vision=image&vision=pdf`). The model must support all listed: `image` (image input), `pdf` (PDF vision input). Use `output=image` to restrict to models that can generate images (supports_image_output).\n\nEach model entry includes standard fields like:\n\n- Unique identifier (`id`)\n- Provider information (`provider`)\n- Vendor information (`vendor`)\n- Model reference name (`name`)\n- Human-readable alias (`alias`)\n- Detailed description (`description`)\n- Vision support status (`supports_vision`) - Whether the model can process images\n- Image output support (`supports_image_output`) - Whether the model can generate images\n- PDF vision support (`supports_pdf_vision`) - Whether the model can process PDFs as visual input, with limits in `pdf_vision_config`\n- Tool calling support (`supports_tool_calling`)\n- Context caching support (`supports_context_caching`)\n- Price tier (`price`) - Coarse comparison tier: cheap, average, or expensive\n- Speed tier (`speed`) - Coarse comparison tier: standard, fast, or ultra fast\n- Knowledge cutoff (`knowledge_cutoff`) - Date of most recent training data, when known\n- Maximum context window (`max_context_window`)\n- Allowed model parameters (`model_params`) - JSON Schema for parameters this model accepts (e.g. `temperature`)\n- Creation and last-modified timestamps (`created`, `modified`)\n- Known issues logged against the model (`llm_model_comments`)\n- When the model was retired (`retired`)\n- The model that replaces it (`replaced_by`)\n\nModels may have different capabilities, performance characteristics, and cost structures.\nChoose models based on your specific needs.\n","operationId":"getAllModels","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"include_retired","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Retired"},"description":"Include models that have been retired."},{"name":"include_excluded","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Include Excluded"},"description":"Include models excluded for this organization or project."},{"name":"vision","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/VisionFilter"}},{"type":"null"}],"title":"Vision"},"description":"Filter by vision (input) capability. Repeat for multiple: image (supports_vision), pdf (supports_pdf_vision). Model must support all listed."},{"name":"output","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/OutputFilter"},{"type":"null"}],"title":"Output"},"description":"Filter by output capability, e.g. image for models that can generate images (supports_image_output)."}],"responses":{"200":{"description":"Successfully retrieved list of available LLM models","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LLMModel"},"title":"Response Getallmodels"},"examples":{"success_including_retired":{"summary":"Available LLM Models (including a retired one)","value":[{"id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z"},{"id":"af2a9bbf-5f36-4b12-bd3f-92c57be96dec","provider":"OpenAI","vendor":"openai","name":"gpt-3.5-turbo","alias":"GPT-3.5 Turbo","description":"Fast, efficient model suitable for simple tasks. 16K context window.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"cheap","speed":"standard","knowledge_cutoff":"2021-09-01","max_context_window":16385,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z"},{"id":"0a15c94b-1f5c-43a0-95f7-8c258e100e27","provider":"Anthropic","vendor":"anthropic","name":"claude-3-opus","alias":"Claude 3 Opus","description":"Most capable Claude 3 model. 200K context window.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":true,"supports_tool_calling":true,"supports_context_caching":true,"price":"expensive","speed":"standard","max_context_window":200000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z"},{"id":"c3847a5f-8b2e-4f8a-b1c9-d238e4a5f3b2","provider":"OpenAI","vendor":"openai","name":"dall-e-3","alias":"DALL-E 3","description":"OpenAI's most capable image generation model. Creates highly detailed and accurate images from text descriptions.","supports_vision":false,"supports_image_output":true,"supports_pdf_vision":false,"supports_tool_calling":false,"supports_context_caching":false,"price":"average","speed":"fast","max_context_window":4000,"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z"},{"id":"36584583-a3d3-463d-a071-c8e88b039eb4","provider":"OpenAI","vendor":"openai","name":"code-davinci-002","alias":"Codex","description":"DEPRECATED. OpenAI Codex model optimized for code completion.","supports_vision":false,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":false,"supports_context_caching":false,"max_context_window":8000,"created":"2022-03-15T00:00:00Z","modified":"2023-03-23T00:00:00Z","retired":"2023-03-23T00:00:00Z","replaced_by":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41"}]}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"MALFORMED_RESOURCE_IDENTIFIER","message":"Resource identifier value provided for field 'project_id' is malformed (expected UUID)","malformedResourceIdentifierError":{"field":"project_id","value":"not-a-uuid","expected_format":"UUID"}}}}},"description":"Bad Request - a path parameter is not a well-formed UUID"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getallmodels"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid path parameters\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid path parameters","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"500":{"description":"Internal Server Error - Failed to retrieve models","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/model/{model_id_or_name}":{"get":{"tags":["Listings"],"summary":"Get Model Details","operationId":"getModel","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"model_id_or_name","in":"path","required":true,"description":"The UUID or name of the LLM model to retrieve (e.g., 'ec217e75-72ea-4281-a1b8-cb7bd0ef9f41' or 'gpt-4-turbo').","schema":{"type":"string"},"examples":{"by_id":{"summary":"Get model by UUID","value":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41"},"by_name":{"summary":"Get model by name","value":"gpt-4-turbo"}}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Successfully retrieved model details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LLMModel"},"example":{"provider":"OpenAI","vendor":"openai","name":"gpt-4-turbo","alias":"GPT-4 Turbo","description":"Latest GPT-4 Turbo model with vision capabilities. 128K context window with training cut off of Dec 2023.","supports_vision":true,"supports_image_output":false,"supports_pdf_vision":false,"supports_tool_calling":true,"supports_context_caching":false,"price":"average","speed":"fast","knowledge_cutoff":"2023-12-01","max_context_window":128000,"model_params":{"temperature":{"type":"number","default":0.3,"maximum":1.0,"minimum":0.0,"description":"Controls randomness in the output. Lower values make output more focused and deterministic."}},"created":"2024-01-16T13:33:25.247662Z","modified":"2024-01-16T13:33:25.247662Z","id":"ec217e75-72ea-4281-a1b8-cb7bd0ef9f41","llm_model_comments":[]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Multiple models found with the same name or identifier"}}},"description":"Bad Request - `model_id_or_name` matched more than one model"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getmodel"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Model not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Model not found"}}}}},"description":"Retrieve detailed information about a specific LLM model by its ID or name.\n\nThis endpoint accepts either a UUID or the model name (e.g., \"gpt-4-turbo\" or \"claude-3-opus\").\n\nReturns complete model information including:\n- Provider and vendor details\n- Model capabilities (vision support, context window)\n- Retirement status and replacement information\n- Disabled parameters\n\nUse this endpoint to:\n- Verify model capabilities before using in a task\n- Check if a model has been retired\n- Look up model details by name for easier integration\n- Get detailed model specifications\n- Find replacement models for retired ones"}},"/org/{org_id}/project/{project_id}/guardrail":{"get":{"tags":["Listings"],"summary":"List Available Guardrails","operationId":"listAvailableGuardrails","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"List of available guardrails","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ChatGuardrail"},"title":"Response Listavailableguardrails"},"examples":{"guardrails":{"summary":"Available Guardrails","value":[{"id":"prompt_policy","name":"Prompt Policy","description":"Enforces that prompt adheres to a policy inline with most LLM vendors (e.g. harmful data, impersonation, ignoring chat rules)","type":"input"},{"id":"pii_policy","name":"PII Policy","description":"Enforces that prompt contains no PII (e.g. email addresses, phone numbers, financial information)","type":"input"}]}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n\n**Resolution:** Send a valid Bearer token in the `Authorization` header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"integer"},"status":{"type":"string"},"reason":{"type":"string"},"message":{"type":"string"}},"required":["code","status","message"]}},"required":["error"]},"examples":{"missing_credentials":{"summary":"No credentials sent","value":{"error":{"code":401,"status":"Unauthorized","message":"Access credentials are invalid"}}},"inactive_token":{"summary":"Token rejected","description":"A token that is expired, revoked or unrecognised adds `reason`.","value":{"error":{"code":401,"status":"Unauthorized","reason":"Access token is not active","message":"Access credentials are invalid"}}}}}}}},"externalDocs":{"description":"Learn more about using guardrails","url":"https://docs.rightbrain.ai/guides/guardrails"},"description":"Retrieve a list of all available guardrails for content validation.\n\n**Note**: This endpoint returns a plain array of guardrails, not a paginated response. All available guardrails are returned in a single request.\n\nRightbrain currently ships two built-in guardrails, both applied to the input prompt before\nit reaches the model:\n\n- **Prompt Policy** (`prompt_policy`) - enforces that the prompt adheres to a policy in line\n  with most LLM vendors' terms (e.g. harmful content, impersonation, attempts to override the\n  system prompt).\n- **PII Policy** (`pii_policy`) - enforces that the prompt contains no personally identifiable\n  information (e.g. email addresses, phone numbers, financial details).\n\nEach entry has an `id`, human-readable `name`, `description`, and a `type` of either `input`\nor `output` describing which side of the model call it's applied to.\n\nUse these guardrail IDs in a task's guardrail configuration to automatically validate output.\n\nThe list is the same for every caller. `org_id` and `project_id` only address the\nroute; they do not scope the result."}},"/org/{org_id}/project/{project_id}/input_processor":{"get":{"tags":["Input Processors"],"summary":"List Input Processors","description":"Returns a list of all available input processors that can be used to transform task inputs.\n\n**Note**: This endpoint returns a plain array of processors, not a paginated response. All available processors are returned in a single request.\n\nInput processors are utility functions that can modify or enhance the input data before it is processed by the task.\nEach processor supports optional configuration parameters to customize its behavior; `config_schema` is `null` for\nprocessors that take no configuration.\n\nAvailable processors:\n- **url_fetcher**: Fetches HTML content from URLs\n- **document_content_extractor**: Extracts text from uploaded documents\n- **audio_transcriber**: Transcribes audio files to text\n- **perplexity_search**: Searches the web for real-time information","operationId":"getInputProcessors","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"Successfully retrieved list of available input processors with their configuration options","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/InputProcessor"},"title":"Response Getinputprocessors"},"examples":{"success":{"summary":"Available Input Processors","value":[{"name":"url_fetcher","description":"Fetches the HTML content for the provided site and replaces the URL with the fetched content.","config_schema":{"additionalProperties":true,"title":"ConfigSchema","type":"object","properties":{"fetch_mode":{"type":"string","enum":["default","direct"],"default":"default","title":"Fetch Mode","description":"How the URL should be fetched. Use 'default' for the standard fetch behavior or 'direct' to fetch the URL directly."},"fallback_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fallback Text","description":"Text to return if hosted fetching fails."}}}},{"name":"document_content_extractor","description":"Extracts the content from a document and replaces the variable with the extracted content."},{"name":"audio_transcriber","description":"Transcribes audio files to text using Google Gemini. Supports WAV, MP3, AIFF, AAC, OGG, and FLAC formats. The transcribed text replaces the audio file in the task input.","config_schema":{"additionalProperties":false,"description":"Configuration for audio transcription.","title":"ConfigSchema","type":"object","properties":{"prompt":{"type":"string","default":"Transcribe this audio.","title":"Prompt","description":"Instruction for the transcription model. Can request summaries, diarisation, structured output, etc."},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Language hint (e.g., 'en', 'es'). Auto-detected if None."},"audio_timestamp":{"type":"boolean","default":false,"title":"Audio Timestamp","description":"Include timestamps in the transcription output."}}}},{"name":"perplexity_search","description":"Searches Perplexity for the provided query and returns ranked web results with optional snippets, dates, and metadata.","config_schema":{"additionalProperties":false,"description":"Configuration schema for Perplexity search","title":"ConfigSchema","type":"object","properties":{"max_results":{"type":"integer","default":5,"minimum":1,"maximum":100,"title":"Max Results","description":"Number of search results to return"},"query_context":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query Context","description":"Template string with single variable placeholder (e.g., '{company}', '{topic}') that will be replaced with user input"},"fallback_text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fallback Text","description":"Text to return on error instead of raising exception"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"Country to target search results origin.","examples":["GB","US"]}}}}]}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid UUID format"}}},"description":"Bad Request - Invalid UUID format\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getinputprocessors"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid path parameters\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid path parameters","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve input processors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/oauth_client/{oauth_client_id}":{"get":{"tags":["OAuth Clients"],"summary":"Get OAuth Client Details","operationId":"getOAuthClient","security":[{"HTTPBearer":[]},{"HTTPBearer":["oauth_client:view"]}],"parameters":[{"name":"oauth_client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Oauth Client Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Org Id"}},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Project Id"}}],"responses":{"200":{"description":"OAuth client details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClient"},"example":{"id":"019f8a01-2b21-7001-9c2b-3b6d0e5f1011","name":"Support Portal","description":"Web app backend for the customer support portal","client_id":"019f8a01-2b21-7002-9c2b-3b6d0e5f1012","client_secret":null,"project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","redirect_uris":["https://support.example.com/oauth/callback"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"client_secret_basic","pkce_required":false,"pkce_challenge_method":null,"created":"2026-02-03T08:05:00Z","modified":"2026-06-11T10:20:00Z","deleted":null}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Getoauthclient"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on oauth_client [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"oauth_client","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for OAuth client\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The OAuth client belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"OAuth client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find oauth_client [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"oauth_client","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to retrieve OAuth client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Retrieve detailed information about a specific OAuth client.\n\nReturns:\n- Identity: `id`, `client_id`, `name`, `description`, and the owning `project_id`\n- Enabled `grant_types` and authorized `redirect_uris`\n- `token_endpoint_auth_method`, `pkce_required` and `pkce_challenge_method`\n- `created`, `modified` and `deleted` timestamps\n\n`client_secret` is included in the response but is always `null` here. The\nsecret is returned exactly once, in the response to creating the client, and\nis not stored afterwards — use `POST .../client_secret` to issue a new one.\n\n`deleted` is likewise always `null`: this lookup excludes soft-deleted\nclients, so a client with a `deleted` timestamp is never returned."},"post":{"tags":["OAuth Clients"],"summary":"Update OAuth Client","operationId":"updateOAuthClient","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_oauth_client"]}],"parameters":[{"name":"oauth_client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Oauth Client Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientUpdate"},"examples":{"add_redirect":{"summary":"Add Redirect URI","value":{"redirect_uris":["https://app.example.com/callback","https://staging.example.com/callback"]}}}}}},"responses":{"200":{"description":"OAuth client updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClient"},"examples":{"Add Redirect URI":{"summary":"Add Redirect URI","value":{"id":"019f8a01-2b21-7001-9c2b-3b6d0e5f1011","name":"Support Portal","description":"Web app backend for the customer support portal","client_id":"019f8a01-2b21-7002-9c2b-3b6d0e5f1012","client_secret":null,"project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","redirect_uris":["https://support.example.com/oauth/callback","https://staging.support.example.com/oauth/callback"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"client_secret_basic","pkce_required":false,"pkce_challenge_method":null,"created":"2026-02-03T08:05:00Z","modified":"2026-07-19T13:45:00Z","deleted":null}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid client configuration"}}},"description":"Bad Request - Invalid client configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Updateoauthclient"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_oauth_client permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_oauth_client"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid configuration\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid configuration","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"OAuth client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find oauth_client [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"oauth_client","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to update OAuth client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Update OAuth client configuration.\n\nModifiable fields:\n- Redirect URIs\n- Grant types\n- Token endpoint authentication method\n- PKCE requirement and challenge method\n\nOnly fields present in the request are changed; omitted fields keep their\ncurrent values. Disabling PKCE also clears any configured challenge method."},"delete":{"tags":["OAuth Clients"],"summary":"Delete OAuth Client","description":"Delete an OAuth client and revoke all access.\n\nThis will:\n- Revoke all active tokens\n- Remove client configuration\n- Delete access logs\n\nThis action cannot be undone.\n\nAnswers `200` with a body of `null` rather than `204 No Content`.","operationId":"deleteOAuthClient","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_oauth_client"]}],"parameters":[{"name":"oauth_client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Oauth Client Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"OAuth client deleted","content":{"application/json":{"schema":{"type":"null"},"example":null}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Deleteoauthclient"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_oauth_client permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_oauth_client"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"OAuth client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find oauth_client [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"oauth_client","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to delete OAuth client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}}}},"/org/{org_id}/project/{project_id}/oauth_client":{"get":{"tags":["OAuth Clients"],"summary":"List OAuth Clients","operationId":"listOAuthClients","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."},{"name":"page_limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"default":100,"title":"Page Limit"},"description":"The maximum number of items to return per page. Defaults to `100` if not specified."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cursor"},"description":"A cursor for pagination. Use the `next_cursor` value from the previous response to get the next page of results."}],"responses":{"200":{"description":"OAuth clients retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_OAuthClient_"},"examples":{"multiple_clients":{"summary":"Multiple OAuth Clients","value":{"results":[{"id":"019f8a01-2b21-7001-9c2b-3b6d0e5f1011","name":"Support Portal","description":"Web app backend for the customer support portal","client_id":"019f8a01-2b21-7002-9c2b-3b6d0e5f1012","client_secret":null,"project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","redirect_uris":["https://support.example.com/oauth/callback"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"client_secret_basic","pkce_required":false,"pkce_challenge_method":null,"created":"2026-02-03T08:05:00Z","modified":"2026-06-11T10:20:00Z","deleted":null},{"id":"019f8a01-2b21-7004-9c2b-3b6d0e5f1014","name":"Driver Mobile App","description":"Native mobile app used by delivery drivers","client_id":"019f8a01-2b21-7005-9c2b-3b6d0e5f1015","client_secret":null,"project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","redirect_uris":["com.example.driverapp://oauth/callback"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"none","pkce_required":true,"pkce_challenge_method":"S256","created":"2026-03-14T09:30:00Z","modified":"2026-03-14T09:30:00Z","deleted":null},{"id":"019f8a01-2b21-7006-9c2b-3b6d0e5f1016","name":"Ops CLI","description":"Command-line tool used by the operations team","client_id":"019f8a01-2b21-7007-9c2b-3b6d0e5f1017","client_secret":null,"project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","redirect_uris":["http://localhost:8080/callback"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"client_secret_basic","pkce_required":false,"pkce_challenge_method":null,"created":"2026-01-20T11:00:00Z","modified":"2026-01-20T11:00:00Z","deleted":null}],"pagination":{"has_next":false,"page_limit":25}}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid pagination"}}},"description":"Bad Request - Invalid pagination\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listoauthclients"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have view permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"view"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"project","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to list OAuth clients","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"List the OAuth clients in this project.\n\nEach item has the same shape as `GET .../oauth_client/{oauth_client_id}`:\nidentity fields, `grant_types`, `redirect_uris`, the token endpoint auth\nmethod and PKCE settings, and `created`/`modified`/`deleted` timestamps.\n`client_secret` is always `null` in list results.\n\nThree filters are applied that a caller cannot turn off:\n- only clients you have permission to view are returned, so two members of the\n  same project may see different lists\n- Rightbrain's own internal clients are excluded; only clients created through\n  this API appear\n- soft-deleted clients are excluded, so `deleted` is always `null`\n\nResults are newest first (descending `id`, which is time-ordered) and\npaginated with `cursor` and `page_limit`."},"post":{"tags":["OAuth Clients"],"summary":"Create OAuth Client","operationId":"createOAuthClient","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_oauth_client"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserOAuthClientCreate"},"examples":{"web_app":{"summary":"Web Application","value":{"name":"Customer Portal","description":"Sign-in for the customer portal.","grant_types":["authorization_code","refresh_token"],"redirect_uris":["https://app.example.com/callback","https://app.example.com/silent-refresh"]}},"service":{"summary":"Service Account","description":"`type: project` is what makes this a service account: the client carries project-level permissions rather than the creating user's, and every project member is granted viewer access to it. The only other accepted value is `user`, the default, which inherits the creating user's permissions (endpoints/oauth_client.py).","value":{"name":"Analytics Service","grant_types":["client_credentials"],"type":"project"}},"mobile_app_pkce":{"summary":"Mobile App with PKCE","value":{"name":"Mobile App","grant_types":["authorization_code","refresh_token"],"redirect_uris":["com.example.app://oauth/callback"],"pkce_required":true,"pkce_challenge_method":"S256","token_endpoint_auth_method":"none"}}}}}},"responses":{"200":{"description":"OAuth client created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClient"},"examples":{"Web Application":{"summary":"Web Application","value":{"id":"019f8a01-2b21-7001-9c2b-3b6d0e5f1011","name":"Support Portal","description":"Web app backend for the customer support portal","client_id":"019f8a01-2b21-7002-9c2b-3b6d0e5f1012","client_secret":"XXXXXXXXXXXXXXXXXXXXXXXXXX","project_id":"019f8a00-1a10-7002-8b1a-2a5c9d4e0002","redirect_uris":["https://support.example.com/oauth/callback"],"grant_types":["authorization_code","refresh_token"],"token_endpoint_auth_method":"client_secret_basic","pkce_required":false,"pkce_challenge_method":null,"created":"2026-02-03T08:05:00Z","modified":"2026-02-03T08:05:00Z","deleted":null}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid client configuration"}}},"description":"Bad Request - Invalid client configuration\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createoauthclient"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_oauth_client permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_oauth_client"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Unprocessable Entity - Invalid configuration\n\n**Common causes:**\n- Request is well-formed but violates business rules\n- Invalid combination of fields (e.g., mutually exclusive options)\n- Referenced resource doesn't exist or is in wrong state\n- Field value is valid type but out of acceptable range\n\n**Resolution:** Check the error message for specific validation failures and adjust your request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":[{"loc":["body"],"msg":"Invalid configuration","type":"value_error"}]}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"409":{"description":"Conflict - Client name already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Client name already exists"}}}},"500":{"description":"Internal Server Error - Failed to create OAuth client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Create a new OAuth client for API access.\n\nOAuth clients enable:\n- Third-party application integration\n- Service-to-service authentication\n- Mobile app authentication\n- CLI tool access\n\n**Choosing the Right Grant Type:**\n\n| Use Case | Grant Type | PKCE | Notes |\n|----------|------------|------|-------|\n| Web app with backend | `authorization_code` | Optional | Most secure for user-facing apps |\n| Mobile/Desktop app | `authorization_code` | Required | Public client, no secret storage |\n| Server-to-server | `client_credentials` | No | For automated services, no user context |\n| Single-page app | `authorization_code` | Required | Use PKCE instead of implicit |\n| Long-lived sessions | Add `refresh_token` | - | Combine with primary grant type |\n\n**Grant Type Details:**\n- **authorization_code**: User authorizes app via browser, app exchanges code for tokens\n- **client_credentials**: Service authenticates directly with client_id/secret (no user)\n- **refresh_token**: Exchange refresh token for new access token (add to other grants)\n- **implicit**: *Deprecated* - Use authorization_code + PKCE instead\n\n**PKCE Support**:\n- Enable PKCE for public clients (mobile apps, SPAs)\n- Supports S256 (SHA-256) and plain challenge methods\n- Required for clients without client secrets\n\n**`type` — user client or service account:**\n\n`type` accepts exactly `\"user\"` (the default) or `\"project\"`, and decides whose\npermissions the client carries. Any other value is rejected with `422`.\n\n- `\"user\"`: the client acts as the user who created it and inherits that\n  user's permissions. Only that user is made an owner of the client.\n- `\"project\"`: a service account is created for the client, so it carries\n  project-level permissions rather than one person's, and every member of the\n  project is granted viewer access to the client. Use this for automation that\n  must keep working after the creating user leaves.\n\n`type` is not echoed back: it appears on no response field, so read it back\nfrom behaviour rather than from the created object.\n\n**Fields silently ignored:** the request model is `UserOAuthClientCreate`. Any\nkey it does not declare is dropped rather than rejected — notably `scopes`,\n`profile` and `access_token_type`, which appeared in older references. Scopes\nare fixed at `offline_access` and the access token type at `opaque`; sending\ndifferent values changes nothing and the create still returns `200`.\n\n`client_secret` is returned only once, in this response — store it securely.\nEvery later read of the client reports `client_secret: null`. Public clients\n(`token_endpoint_auth_method: \"none\"`) are issued no secret at all, so their\ncreate response also carries `null`."}},"/org/{org_id}/project/{project_id}/oauth_client/{oauth_client_id}/client_secret":{"post":{"tags":["OAuth Clients"],"summary":"Regenerate Client Secret","operationId":"regenerateOAuthClientSecret","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:create_oauth_client"]}],"parameters":[{"name":"oauth_client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Oauth Client Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientUpdate"},"examples":{"regenerate":{"summary":"Regenerate Secret Request","value":{},"description":"Empty object required to confirm regeneration"}}}}},"responses":{"200":{"description":"New secret generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthClientRegenerateSecretResponse"},"examples":{"Regenerate Secret Request":{"summary":"Regenerate Secret Request","value":{"client_secret":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Regenerateoauthclientsecret"},"example":{"detail":{"reason":"PERMISSION_CHECK_FAILED","message":"user [0190c234-1111-2222-3333-444444444444] does not have create_oauth_client permission on project [019a58ec-43b5-a1e5-60a8-c9653e6badbe] (or it may not exist)","permissionCheckFailedError":{"subject":{"type":"user","id":"0190c234-1111-2222-3333-444444444444"},"resource":{"type":"project","id":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"},"permission":"create_oauth_client"}}}}},"description":"Forbidden - Insufficient permissions for project\n\n**Common causes:**\n- Your role lacks the required permission for this action\n- The project belongs to a different organization or project\n- The action requires admin or owner privileges\n\n**Resolution:** Contact your organization admin to request appropriate access."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"401":{"description":"Unauthorized - Authentication failed\n\n**Common causes:**\n- Missing `Authorization` header\n- Expired access token\n- Invalid or malformed token\n- Using API key in wrong format\n\n**Resolution:** Ensure you're including a valid Bearer token or API key in the Authorization header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"OAuth client not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find oauth_client [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"oauth_client","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}},"500":{"description":"Internal Server Error - Failed to regenerate secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Internal Server Error"}},"text/plain":{"schema":{"type":"string"},"example":"Internal Server Error"}}}},"description":"Generate a new client secret for an OAuth client.\n\nThis will:\n- Invalidate the current secret immediately\n- Generate a new secure secret\n- Return the new secret (only once!)\n\nActive tokens remain valid but cannot be refreshed with old secret."}},"/org/{org_id}/project/{project_id}/oauth_client/{oauth_client_id}/iam/members":{"get":{"tags":["OAuth Clients"],"summary":"IAM - List Project Members","description":"Lists all members that have been granted direct access to the project.","operationId":"project_iam_org_org_id_project_project_id_oauth_client_oauth_client_id_iam_list_members","security":[{"HTTPBearer":[]},{"HTTPBearer":["oauth_client:view","project:view_members"]}],"parameters":[{"name":"oauth_client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Oauth Client Id"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"enum":["user","organization","project"],"type":"string"},{"type":"null"}],"title":"Type"},"description":"Returns only members of this subject type. Omit it to return members of every subject type."},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Successfully retrieved Project members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResultSet_IAMMember_"},"example":{"pagination":{"next_cursor":null,"has_next":false,"page_limit":0},"results":[{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Iam Org Org Id Project Project Id Oauth Client Oauth Client Id Iam List Members"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/oauth_client/{oauth_client_id}/iam/members/{member}":{"get":{"tags":["OAuth Clients"],"summary":"IAM - Lookup Project Member","description":"Retrieve a specific member that has been granted direct access to the project.","operationId":"project_iam_org_org_id_project_project_id_oauth_client_oauth_client_id_iam_get_member","security":[{"HTTPBearer":[]},{"HTTPBearer":["oauth_client:view","project:view_members"]}],"parameters":[{"name":"oauth_client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Oauth Client Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"responses":{"200":{"description":"Project member details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"example":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Iam Org Org Id Project Project Id Oauth Client Oauth Client Id Iam Get Member"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["OAuth Clients"],"summary":"IAM - Update Project Member","description":"Update the roles that a member holds on the project.","operationId":"project_iam_org_org_id_project_project_id_oauth_client_oauth_client_id_iam_update_member_roles","security":[{"HTTPBearer":[]},{"HTTPBearer":["oauth_client:view"]}],"parameters":[{"name":"oauth_client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Oauth Client Id"}},{"name":"member","in":"path","required":true,"schema":{"type":"string","title":"Member"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectIAMMemberRoleUpdate"},"examples":{"replace_roles":{"summary":"Replace the member's roles","value":{"add":["owner"],"remove_all":true}}}}}},"responses":{"200":{"description":"Project member updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMMember"},"examples":{"Replace the member's roles":{"summary":"Replace the member's roles","value":{"member":"user:0190c234-1111-2222-3333-444444444444","roles":["owner"],"name":"Carlos Reyes","avatar_url":null,"total_subjects":1}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Project Iam Org Org Id Project Project Id Oauth Client Oauth Client Id Iam Update Member Roles"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Iam Org Org Id Project Project Id Oauth Client Oauth Client Id Iam Update Member Roles"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/oauth_client/{oauth_client_id}/iam/test":{"post":{"tags":["OAuth Clients"],"summary":"IAM - Test Project Permissions","description":"Test the permissions that the caller (or another subject) holds on the project.","operationId":"project_iam_org_org_id_project_project_id_oauth_client_oauth_client_id_iam_test_permissions","security":[{"HTTPBearer":[]},{"HTTPBearer":["oauth_client:view"]}],"parameters":[{"name":"oauth_client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Oauth Client Id"}},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The org id"},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The project id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectIAMPermissionTest"},"examples":{"test_permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["view","edit","view_members"]}}}}}},"responses":{"200":{"description":"Project permissions tested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IAMPermissionTest"},"examples":{"Test the caller's own permissions":{"summary":"Test the caller's own permissions","value":{"permissions":["edit","view","view_members"],"member":"user:0190c234-1111-2222-3333-444444444444"}}}}}},"400":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/InvalidMemberErrorResponse"},{"$ref":"#/components/schemas/InvalidRoleErrorResponse"},{"$ref":"#/components/schemas/InvalidSubjectTypeErrorResponse"},{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}],"title":"Response 400 Project Iam Org Org Id Project Project Id Oauth Client Oauth Client Id Iam Test Permissions"}}},"description":"Bad Request"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvalidMemberErrorResponse"}}},"description":"Not Found"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Project Iam Org Org Id Project Project Id Oauth Client Oauth Client Id Iam Test Permissions"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/org/{org_id}/project/{project_id}/api_key":{"post":{"tags":["API Keys"],"summary":"Create API Key","operationId":"createApiKey","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"},"examples":{"basic":{"summary":"Basic API Key","value":{"name":"Production API Key"}},"named":{"summary":"Named for its purpose","value":{"name":"CI/CD Pipeline Key"}}}}}},"responses":{"200":{"description":"API key created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"},"examples":{"Basic API Key":{"summary":"Basic API Key","value":{"id":"019f8a02-3c32-7001-ad3c-4c7e1f602021","name":"CI/CD Pipeline Key","key":"ory_at_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","oauth_client_id":"019f8a01-2b21-7003-9c2b-3b6d0e5f1013","created":"2026-07-26T09:15:00.280861","expires_at":"2046-07-21T09:15:00.580875Z","revoked":false}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid request"}}},"description":"Bad Request - Invalid request\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Createapikey"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"Create a new API key for authenticating API requests.\n\nAPI keys provide a simpler alternative to OAuth for programmatic access. Each key:\n- Is tied to the creating user and inherits their permissions\n- Can be used to authenticate requests to any project endpoint\n- Has a descriptive name for easy management\n- Can be revoked at any time\n\nThe API key is only shown once at creation time and cannot be retrieved later.\n\n**Security Notes**:\n- Store API keys securely (use environment variables, not hardcode)\n- Rotate keys regularly\n- Each key inherits the user's project permissions\n- Revoke compromised keys immediately"},"get":{"tags":["API Keys"],"summary":"List API Keys","operationId":"listApiKeys","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"List of API keys","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"},"title":"Response Listapikeys"},"examples":{"multiple_keys":{"summary":"Multiple API Keys","value":[{"id":"019f8a02-3c32-7001-ad3c-4c7e1f602021","name":"CI/CD Pipeline Key","key":"ory_at_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","oauth_client_id":"019f8a01-2b21-7003-9c2b-3b6d0e5f1013","created":"2026-06-01T09:15:00.114203","expires_at":"2046-05-27T09:15:00.114203Z","last_used":"2026-07-25T11:42:03.881442Z","revoked":false},{"id":"019f8a02-3c32-7002-ad3c-4c7e1f602022","name":"Nightly Reporting Key","key":"ory_at_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","oauth_client_id":"019f8a01-2b21-7003-9c2b-3b6d0e5f1013","created":"2026-06-10T07:00:00.442210","expires_at":"2046-06-05T07:00:00.442210Z","revoked":false}]}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Invalid request"}}},"description":"Bad Request - Invalid request\n\n**Common causes:**\n- Invalid UUID format in path or query parameters\n- Missing required fields in the request body\n- Invalid enum value provided\n- Type mismatch (e.g., string instead of number)\n\n**Resolution:** Check the request body and parameters match the schema."},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Listapikeys"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"description":"List all active API keys for the current user in the specified project.\n\n**Note**: This endpoint returns a plain array of API keys, not a paginated response. All API keys for the user are returned in a single request.\n\nReturns all non-revoked API keys created by the authenticated user for the project.\nKeys are returned in descending order by creation date.\n\n**Response Fields:**\n- `id`: Unique identifier for the API key\n- `name`: Human-readable name for the key\n- `key`: The API key value\n- `oauth_client_id`: The OAuth client this API key is associated with\n- `expires_at`: When the backing long-lived Hydra token expires\n- `last_used`: Timestamp of when the key was last used for authentication, if ever\n- `created`: When the key was created\n- `revoked`: Whether the key has been revoked\n\n**Security note**: This endpoint returns the full, usable key value on every\ncall, not just at creation time. Treat list responses as sensitive and avoid\nlogging them."}},"/org/{org_id}/project/{project_id}/api_key/{api_key_id}/revoke":{"post":{"tags":["API Keys"],"summary":"Revoke API Key","operationId":"revokeApiKey","security":[{"HTTPBearer":[]},{"HTTPBearer":["project:view"]}],"parameters":[{"name":"api_key_id","in":"path","required":true,"description":"The UUID of the API key to revoke","schema":{"type":"string","format":"uuid"},"example":"019f8a02-3c32-7001-ad3c-4c7e1f602021"},{"name":"org_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174000"],"title":"Org Id"},"description":"The unique identifier of the organization."},{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","examples":["123e4567-e89b-12d3-a456-426614174001"],"title":"Project Id"},"description":"The unique identifier of the project."}],"responses":{"200":{"description":"API key revoked successfully","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Revokeapikey"},"examples":{"success":{"summary":"Revoked Successfully","value":{"success":true}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorResponse"}}},"description":"Bad Request"},"403":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/PermissionCheckFailedErrorResponse"},{"$ref":"#/components/schemas/MissingAuthenticationErrorResponse"}],"title":"Response 403 Revokeapikey"}}},"description":"Forbidden"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"api_keys not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find api_keys [019a58ec-43b5-a1e5-60a8-c9653e6badbe]","resourceNotFoundError":{"field":"api_keys","value":"019a58ec-43b5-a1e5-60a8-c9653e6badbe"}}}}}}},"description":"Revoke an existing API key to prevent further use.\n\nOnce revoked:\n- The key immediately becomes invalid for authentication\n- All requests using the key will receive 401 Unauthorized\n- The action cannot be undone\n- The key will no longer appear in listings\n\nOnly the user who created the key can revoke it."}},"/public/{project_key}/llms/task/{task_id}":{"get":{"tags":["Agent Pack"],"summary":"Get Task for LLM/Agent Consumption","description":"Retrieve a task's information in a format optimized for LLMs and agents to consume.\n\nThis endpoint provides task details in a plaintext format that includes:\n- Task name and description\n- Input parameters with their types and descriptions\n- Output format specification\n- Example usage and integration instructions\n- OAuth/API authentication details\n- Links to full documentation\n\nThe response is designed to be easily parsed by LLMs and can be used to:\n- Understand how to integrate with RightBrain tasks\n- Generate code for task execution\n- Learn about required inputs and expected outputs\n- Access authentication endpoints\n\n**Authentication**: This endpoint requires a valid project routing key (no user authentication needed).\n\n**Use Cases**:\n- LLM agents discovering available tasks\n- Automated documentation generation\n- Task discovery and integration\n- Agent-based task execution","operationId":"getTaskForLlm","parameters":[{"name":"project_key","in":"path","required":true,"description":"The unique public routing key for the project","schema":{"type":"string"},"example":"prj_1234567890abcdef"},{"name":"task_id","in":"path","required":true,"description":"The UUID of the task to retrieve","schema":{"type":"string","format":"uuid"},"example":"550e8400-e29b-41d4-a716-446655440000"}],"responses":{"200":{"description":"Task information formatted for LLM consumption","content":{"text/plain":{"schema":{"type":"string"},"example":"# Rightbrain API Task Guide for Agents\n\nThis guide provides all the information needed to programmatically call a Rightbrain API task, including authentication, request formatting, and response handling.\n\n**Additional Resources:**\n- **Complete API Documentation:** https://docs.rightbrain.ai\n- **Full API Reference (LLM-optimized):** https://docs.rightbrain.ai/llms-full.txt\n\n## Task Overview\n\n**Task Name:** Analyze Customer Sentiment\n**Description:** Analyzes customer feedback and returns sentiment scores.\n**API Endpoint:** https://app.rightbrain.ai/api/v1/org/0190a234-8dc6-6d08-aea9-928fcecad8f1/project/0190a234-8dc6-6d08-aea9-928fcecad8f2/task/550e8400-e29b-41d4-a716-446655440000/run\n\n## Authentication\n\nRightbrain supports two authentication methods. **API Keys are recommended** for most automated agents and scripts due to their simplicity.\n\n### Method 1: API Keys (Recommended)\n\nStatic, long-lived API keys are the simplest way to authenticate with the Rightbrain API.\n\n#### Step 1: Create an API Key\n\n1. Navigate to the Rightbrain dashboard: https://app.rightbrain.ai/preferences?tab=api-clients\n2. Click \"Create API Key\"\n3. Provide a descriptive name for your key\n4. Copy the generated API key immediately (it's shown only once)\n\n#### Step 2: Use the API Key\n\nInclude your API key in the `Authorization` header using the `Bearer` scheme:\n\n```bash\nAuthorization: Bearer YOUR_API_KEY\n```\n\n**Complete Example:**\n```bash\nAPI_KEY=\"your_api_key_here\"\n\ncurl -s \"https://app.rightbrain.ai/api/v1/org/0190a234-8dc6-6d08-aea9-928fcecad8f1/project/0190a234-8dc6-6d08-aea9-928fcecad8f2/task/550e8400-e29b-41d4-a716-446655440000/run\" \\\n     -X POST \\\n     -H \"Authorization: Bearer $API_KEY\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"task_input\": [\"customer_feedback\", \"include_themes\"]}'\n```\n\n### Method 2: OAuth 2.0 Client Credentials (Alternative)\n\n**OAuth 2.0 Endpoints:**\n- **Authorization URL:** https://oauth.rightbrain.ai/oauth2/auth\n- **Token URL:** https://oauth.rightbrain.ai/oauth2/token\n\nCreate an OAuth client from the dashboard, then exchange the client ID/secret for an access\ntoken via `grant_type=client_credentials` before calling the task endpoint the same way as\nabove with `Authorization: Bearer $TOKEN`. Tokens expire (typically after 1 hour) and are not\nissued with a refresh token, so request a new one when needed.\n\n## Task Input Parameters\n\nThis task requires the following input parameters:\n\n```json\n[\"customer_feedback\", \"include_themes\"]\n```\n\n**Parameter Guidelines:**\n- All parameters should be included in the `task_input` field as JSON\n- Parameter names are case-sensitive\n- Ensure proper JSON formatting with escaped quotes where necessary\n\n## Content-Type Options\n\n1. **`Content-Type: application/json`** - Use for JSON-only requests\n2. **`Content-Type: multipart/form-data`** - Use when uploading files (required for tasks\n   that accept images; send `task_input` as a form field with a JSON string value)\n\n## Expected Output\n\nThe API returns a JSON response with the following structure in the `response` field:\n\n```json\n{\"sentiment_score\": {\"type\": \"str\", \"description\": \"number between -1 and 1\"}, \"sentiment_label\": {\"type\": \"str\", \"description\": \"positive, negative, or neutral\"}}\n```\n\n## Response Handling\n\n### Successful Response (HTTP 200)\n\n```json\n{\n  \"task_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"response\": {\n    // Task-specific output matching the format above\n  },\n  \"is_error\": false,\n  \"id\": \"execution_id_uuid\",\n  \"created\": \"2024-01-01T12:00:00Z\",\n  \"input_tokens\": 123,\n  \"output_tokens\": 456,\n  \"total_tokens\": 579\n}\n```\n\n### Error Response Handling\n\n**Authentication Errors (HTTP 401):**\n```json\n{\"error\": \"unauthorized\", \"error_description\": \"The access token expired\"}\n```\n\n**Validation Errors (HTTP 422):**\n```json\n{\"detail\": [{\"loc\": [\"task_input\", \"required_param\"], \"msg\": \"field required\", \"type\": \"value_error.missing\"}]}\n```\n\n**Task Execution Errors (HTTP 200 with `is_error: true`):**\n```json\n{\n  \"task_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"response\": {\"error\": \"Task execution failed: detailed error message\"},\n  \"is_error\": true,\n  \"id\": \"execution_id_uuid\",\n  \"created\": \"2024-01-01T12:00:00Z\"\n}\n```\n\n## Best Practices for Agents\n\n1. Store API keys securely and rotate them periodically\n2. Always check the `is_error` field before processing results\n3. Implement exponential backoff for 429 (Too Many Requests) responses\n4. Never log authentication credentials\n5. Validate input parameters before making API calls\n\n## Troubleshooting\n\n- **401 Unauthorized** - invalid or expired API key/token\n- **403 Forbidden** - the API key doesn't have access to this project\n- **422 Validation Error** - check parameter names and types\n- **429 Too Many Requests** - implement backoff and retry\n- **500 Internal Server Error** - retry with exponential backoff\n\nFor additional support, refer to the full API documentation at: https://docs.rightbrain.ai\n"}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"404":{"description":"Task or project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_project":{"summary":"Invalid Project Key","value":{"detail":"Invalid project key"}},"task_not_found":{"summary":"Task Not Found","value":{"detail":"Task not found for the specified project"}},"no_active_revision":{"summary":"No Active Revision","value":{"detail":"No active revision found for this task"}},"generic_not_found":{"summary":"Task ID Does Not Exist","description":"Returned whenever `task_id` cannot be found at all (the most common case in practice).","value":{"detail":"Task not found or project key is invalid"}}}}}}},"externalDocs":{"description":"Learn more about Agent Packs","url":"https://docs.rightbrain.ai/guides/agent-integration"},"x-fern-ignore":true}},"/whoami":{"get":{"tags":["System"],"summary":"Get Current User","description":"Get current authenticated user information including token details.\n\nReturns the authenticated user's basic information (ID, email, name).\nIf authenticated via OAuth client credentials, also includes the client's\norganization and project context.","operationId":"whoami","responses":{"200":{"description":"Current user information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WhoAmIResponse"},"examples":{"user_session":{"summary":"User authenticated via session","value":{"id":"01234567-89ab-cdef-0123-456789abcdef","email":"user@example.com","name":"Jane Doe"}},"oauth_client":{"summary":"OAuth client authentication","value":{"id":"01234567-89ab-cdef-0123-456789abcdef","email":"service@example.com","name":"Service Account","client":{"org_id":"018936f0-03ea-e8be-a1a1-00000012b0a1","project_id":"019936f0-03ea-e8be-a1a1-00000012c0b2"}}}}}}},"401":{"description":"Not authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":"Not authenticated"}}}},"404":{"description":"The authenticated Hydra client has not been provisioned in Rightbrain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find oauth_client [019a72d4-91a7-7c33-9f64-8a7b6c5d4321]","resourceNotFoundError":{"field":"oauth_client","value":"019a72d4-91a7-7c33-9f64-8a7b6c5d4321"}}}}}}},"security":[{"HTTPBearer":[]}]}},"/-/health":{"get":{"summary":"<Lambda>","operationId":"_lambda____health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"x-generated-operation-id":true}},"/-/ready":{"get":{"summary":"Endpoint","operationId":"endpoint___ready_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"x-generated-operation-id":true}}},"components":{"schemas":{"Account":{"properties":{"org_id":{"type":"string","format":"uuid","title":"Org Id"},"credits":{"type":"integer","title":"Credits","default":0},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"},"id":{"type":"string","format":"uuid","title":"Id"}},"type":"object","required":["org_id","id"],"title":"Account"},"ApiKey":{"properties":{"name":{"type":"string","title":"Name"},"id":{"type":"string","format":"uuid","title":"Id"},"key":{"type":"string","title":"Key"},"oauth_client_id":{"type":"string","format":"uuid","title":"Oauth Client Id"},"created":{"type":"string","format":"date-time","title":"Created"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"last_used":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used"},"revoked":{"type":"boolean","title":"Revoked"}},"type":"object","required":["name","id","key","oauth_client_id","created","expires_at","revoked"],"title":"ApiKey","description":"Schema for returning an API Key to the client."},"ApiKeyCreate":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"ApiKeyCreate","description":"Schema for creating an API Key."},"AsyncJobResult":{"properties":{"status":{"type":"string","title":"Status"},"task_id":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Id"}},"type":"object","required":["status","task_id"],"title":"AsyncJobResult"},"AuditEventDetail":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"org_id":{"type":"string","format":"uuid","title":"Org Id"},"actor_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor User Id"},"event_type":{"type":"string","title":"Event Type"},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id"},"message":{"type":"string","title":"Message"},"labels":{"additionalProperties":true,"type":"object","title":"Labels"},"occurred_at":{"type":"string","title":"Occurred At"},"created":{"type":"string","title":"Created"},"payload":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload"}},"type":"object","required":["id","project_id","org_id","actor_user_id","event_type","resource_type","resource_id","message","labels","occurred_at","created","payload"],"title":"AuditEventDetail"},"AuditEventListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"org_id":{"type":"string","format":"uuid","title":"Org Id"},"actor_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor User Id"},"event_type":{"type":"string","title":"Event Type"},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id"},"message":{"type":"string","title":"Message"},"labels":{"additionalProperties":true,"type":"object","title":"Labels"},"occurred_at":{"type":"string","title":"Occurred At"},"created":{"type":"string","title":"Created"}},"type":"object","required":["id","project_id","org_id","actor_user_id","event_type","resource_type","resource_id","message","labels","occurred_at","created"],"title":"AuditEventListItem"},"AuditIntegrityFailure":{"properties":{"sequence_num":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sequence Num"},"audit_event_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Audit Event Id"},"reason":{"type":"string","title":"Reason"},"expected_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expected Hash"},"actual_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actual Hash"}},"type":"object","required":["reason"],"title":"AuditIntegrityFailure"},"AuditIntegrityStatus":{"properties":{"project_id":{"type":"string","format":"uuid","title":"Project Id"},"verified":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Verified"},"state_verified":{"type":"boolean","title":"State Verified"},"latest_sequence":{"type":"integer","title":"Latest Sequence"},"latest_event_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Latest Event Id"},"latest_event_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Event Hash"},"first_failure":{"anyOf":[{"$ref":"#/components/schemas/AuditIntegrityFailure"},{"type":"null"}]}},"type":"object","required":["project_id","verified","state_verified","latest_sequence"],"title":"AuditIntegrityStatus"},"AuditIntegrityVerification":{"properties":{"verified":{"type":"boolean","title":"Verified"},"status":{"type":"string","title":"Status"},"checked_events":{"type":"integer","title":"Checked Events"},"latest_sequence":{"type":"integer","title":"Latest Sequence"},"latest_event_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Latest Event Id"},"latest_event_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Latest Event Hash"},"first_failure":{"anyOf":[{"$ref":"#/components/schemas/AuditIntegrityFailure"},{"type":"null"}]}},"type":"object","required":["verified","status","checked_events","latest_sequence"],"title":"AuditIntegrityVerification"},"AvailableSkillRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"display_name":{"type":"string","title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License"},"compatibility":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compatibility"},"source":{"$ref":"#/components/schemas/SkillSourceRead"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"has_active_revision":{"type":"boolean","title":"Has Active Revision"},"has_capabilities":{"type":"boolean","title":"Has Capabilities"},"requires_prerequisites":{"type":"boolean","title":"Requires Prerequisites"},"active_revision":{"anyOf":[{"$ref":"#/components/schemas/SkillRevisionSummary"},{"type":"null"}]},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"project_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Project Id"},"created_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By User Id"},"scope":{"type":"string","enum":["global","project"],"title":"Scope"}},"type":"object","required":["id","slug","display_name","description","license","compatibility","source","tags","has_active_revision","has_capabilities","requires_prerequisites","active_revision","created","modified","project_id","created_by_user_id","scope"],"title":"AvailableSkillRead"},"Body_createDocuments":{"properties":{"data":{"type":"string","contentMediaType":"application/json","contentSchema":{"items":{"$ref":"#/components/schemas/ChatDocumentUpload"},"type":"array"},"title":"Data"},"files":{"anyOf":[{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array"},{"type":"null"}],"title":"Files"}},"type":"object","required":["data"],"title":"Body_createDocuments"},"Body_generateContent":{"properties":{"compose":{"$ref":"#/components/schemas/ComposeGenerate"},"context":{"$ref":"#/components/schemas/ComposeInit"}},"type":"object","required":["compose","context"],"title":"Body_generateContent"},"Body_generateTalkingPoints":{"properties":{"context":{"$ref":"#/components/schemas/ComposeInit"},"existing_content":{"$ref":"#/components/schemas/ComposeContent"},"update_instruction":{"$ref":"#/components/schemas/ComposeSectionTalkingPoint"}},"type":"object","required":["context","existing_content","update_instruction"],"title":"Body_generateTalkingPoints"},"Body_updateOrgAvatar":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_updateOrgAvatar"},"Body_updatePartnerAvatar":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_updatePartnerAvatar"},"Body_updateProjectAvatar":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_updateProjectAvatar"},"Body_updateSection":{"properties":{"context":{"$ref":"#/components/schemas/ComposeInit"},"existing_content":{"$ref":"#/components/schemas/ComposeContent"},"update_instruction":{"$ref":"#/components/schemas/ComposeSectionUpdate"}},"type":"object","required":["context","existing_content","update_instruction"],"title":"Body_updateSection"},"Body_uploadProjectDocuments":{"properties":{"data":{"type":"string","contentMediaType":"application/json","contentSchema":{"items":{"$ref":"#/components/schemas/ChatDocumentUpload"},"type":"array"},"title":"Data"},"files":{"anyOf":[{"items":{"type":"string","contentMediaType":"application/octet-stream"},"type":"array"},{"type":"null"}],"title":"Files"}},"type":"object","required":["data"],"title":"Body_uploadProjectDocuments"},"Body_uploadUserAvatar":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"}},"type":"object","required":["file"],"title":"Body_uploadUserAvatar"},"ChatDocument":{"properties":{"title":{"type":"string","title":"Title"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"source":{"anyOf":[{"$ref":"#/components/schemas/DocumentSource"},{"type":"null"}]},"strategy":{"type":"string","title":"Strategy"},"source_meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Source Meta"},"connection_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connection Id"},"id":{"type":"string","format":"uuid","title":"Id"},"chunks":{"type":"integer","title":"Chunks"},"original_mime":{"type":"string","title":"Original Mime"},"embedding_instances":{"anyOf":[{"items":{"$ref":"#/components/schemas/ChatDocumentEmbeddingInstance"},"type":"array"},{"type":"null"}],"title":"Embedding Instances"}},"type":"object","required":["title","project_id","strategy","id","chunks","original_mime","embedding_instances"],"title":"ChatDocument"},"ChatDocumentEmbeddingInstance":{"properties":{"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config","default":{}},"id":{"type":"string","format":"uuid","title":"Id"},"chat_document_id":{"type":"string","format":"uuid","title":"Chat Document Id"},"is_active":{"type":"boolean","title":"Is Active"}},"type":"object","required":["id","chat_document_id","is_active"],"title":"ChatDocumentEmbeddingInstance"},"ChatDocumentEmbeddingRecord":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"document":{"type":"string","title":"Document"}},"type":"object","required":["id","document"],"title":"ChatDocumentEmbeddingRecord"},"ChatDocumentQueryResult":{"properties":{"chat_document_id":{"type":"string","format":"uuid","title":"Chat Document Id"},"text":{"type":"string","title":"Text"},"score":{"type":"number","title":"Score"}},"type":"object","required":["chat_document_id","text","score"],"title":"ChatDocumentQueryResult"},"ChatDocumentUpdate":{"properties":{"title":{"type":"string","title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"}},"type":"object","required":["title"],"title":"ChatDocumentUpdate"},"ChatDocumentUpload":{"properties":{"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"strategy":{"type":"string","title":"Strategy"},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config","default":{}},"target":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Target"},"source":{"$ref":"#/components/schemas/DocumentSource","default":"upload"},"source_meta":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Source Meta"},"collection_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collection Id"}},"type":"object","required":["strategy"],"title":"ChatDocumentUpload"},"ChatGuardrail":{"properties":{"id":{"anyOf":[{"type":"string","const":"source_validation"},{"type":"string","enum":["prompt_policy","pii_policy"]}],"title":"Id"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"type":{"type":"string","enum":["input","output"],"title":"Type"}},"type":"object","required":["id","name","description","type"],"title":"ChatGuardrail"},"Collection":{"properties":{"title":{"type":"string","title":"Title"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"id":{"type":"string","format":"uuid","title":"Id"},"summary":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Summary"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"embedding_instances":{"items":{"$ref":"#/components/schemas/ChatDocumentEmbeddingInstance"},"type":"array","title":"Embedding Instances","default":[]},"task_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Ids","default":[]}},"type":"object","required":["title","project_id","id","created","modified"],"title":"Collection"},"CollectionCreate":{"properties":{"title":{"type":"string","title":"Title"},"document_embedding_instance_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Document Embedding Instance Ids","default":[]}},"type":"object","required":["title"],"title":"CollectionCreate","description":"'Meta schema to enable passing non-standard\nproperties on POST for create"},"CollectionEmbeddingUpdate":{"properties":{"embedding_instance_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Embedding Instance Ids"}},"type":"object","required":["embedding_instance_ids"],"title":"CollectionEmbeddingUpdate"},"CollectionIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of collection roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of collection roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"CollectionIAMMemberRoleUpdate"},"CollectionIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_document","add_editor","add_member","add_owner","create_chat","edit","list_chats","query","remove_document","remove_editor","remove_member","remove_owner","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the collection."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"CollectionIAMPermissionTest"},"CollectionQuery":{"properties":{"query":{"type":"string","title":"Query"},"limit":{"type":"integer","title":"Limit","default":10}},"type":"object","required":["query"],"title":"CollectionQuery","description":"Schema for querying collection content"},"CollectionQueryResult":{"properties":{"response":{"type":"string","title":"Response"},"query":{"type":"string","title":"Query"}},"type":"object","required":["response","query"],"title":"CollectionQueryResult"},"CollectionStatsResponse":{"properties":{"documents_by_source":{"items":{"$ref":"#/components/schemas/SourceRow"},"type":"array","title":"Documents By Source"},"number_of_chats":{"type":"integer","title":"Number Of Chats"}},"type":"object","required":["documents_by_source","number_of_chats"],"title":"CollectionStatsResponse"},"CollectionUpdate":{"properties":{"title":{"type":"string","title":"Title"}},"type":"object","required":["title"],"title":"CollectionUpdate"},"ComposeContent":{"properties":{"existing_content":{"type":"string","title":"Existing Content"}},"type":"object","required":["existing_content"],"title":"ComposeContent"},"ComposeGenerate":{"properties":{"structure":{"items":{"$ref":"#/components/schemas/InitialComposeSection"},"type":"array","title":"Structure"}},"type":"object","required":["structure"],"title":"ComposeGenerate"},"ComposeInit":{"properties":{"title":{"type":"string","title":"Title"},"topic":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Topic"},"purpose":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Purpose"},"audience":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Audience"},"num_sections":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Num Sections"},"word_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Word Count"},"voice":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Voice"},"domain":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"},"tone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tone"},"favourable_words":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Favourable Words"},"deny_words":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deny Words"},"keywords":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keywords"},"cta":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cta"},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content"},"language":{"type":"string","enum":["english_british","english_american","french","chinese","spanish","korean","italian","german"],"title":"Language","default":"english_british"}},"type":"object","required":["title"],"title":"ComposeInit"},"ComposeSectionTalkingPoint":{"properties":{"section_heading":{"type":"string","title":"Section Heading"}},"type":"object","required":["section_heading"],"title":"ComposeSectionTalkingPoint"},"ComposeSectionUpdate":{"properties":{"position":{"type":"integer","title":"Position"},"section_title":{"type":"string","title":"Section Title"},"instructions":{"items":{"type":"string"},"type":"array","title":"Instructions"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"}},"type":"object","required":["position","section_title","instructions"],"title":"ComposeSectionUpdate"},"ComposeTopicPoint":{"properties":{"category":{"type":"string","title":"Category","default":"blog"},"title":{"type":"string","title":"Title"}},"type":"object","required":["title"],"title":"ComposeTopicPoint"},"ConversationalGuardrails":{"properties":{"input":{"items":{"$ref":"#/components/schemas/InputConversationalGuardrailDefinition"},"type":"array","title":"Input","description":"List of valid Input Conversational Guardrails to enable","default":[]},"output":{"items":{"$ref":"#/components/schemas/OutputConversationalGuardrailDefinition"},"type":"array","title":"Output","description":"List of valid Output Conversational Guardrails to enable","default":[],"examples":["[\"prompt_policy\"]"]}},"type":"object","title":"ConversationalGuardrails"},"Datasource":{"properties":{"name":{"type":"string","title":"Name"},"id":{"type":"string","format":"uuid","title":"Id"}},"type":"object","required":["name","id"],"title":"Datasource"},"DatasourceConnection":{"properties":{"private":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Private"},"project_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Project Id"},"datasource_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Datasource Id"},"config":{"additionalProperties":true,"type":"object","title":"Config","default":{}},"token":{"type":"string","title":"Token","default":""},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"id":{"type":"string","format":"uuid","title":"Id"}},"type":"object","required":["id"],"title":"DatasourceConnection"},"DatasourceConnectionPublic":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"private":{"type":"boolean","title":"Private"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"datasource_id":{"type":"string","format":"uuid","title":"Datasource Id"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"config":{"additionalProperties":true,"type":"object","title":"Config","default":{}},"datasource":{"$ref":"#/components/schemas/Datasource"}},"type":"object","required":["id","name","private","project_id","datasource_id","created","modified","datasource"],"title":"DatasourceConnectionPublic"},"DatasourceSyncRun":{"properties":{"task_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Id"},"status":{"type":"string","enum":["pending","started","success","failure","retry","progress"],"title":"Status","default":"pending"},"run_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Run Output","default":{}},"id":{"type":"string","format":"uuid","title":"Id"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"datasource_connection":{"anyOf":[{"$ref":"#/components/schemas/DatasourceConnection"},{"type":"null"}]}},"type":"object","required":["id","created","modified"],"title":"DatasourceSyncRun"},"DocumentCreateTask":{"properties":{"task_id":{"type":"string","title":"Task Id"},"state":{"type":"string","enum":["PENDING","RECEIVED","STARTED","PROGRESS","SUCCESS","FAILURE","RETRY","REVOKED","REJECTED","IGNORED"],"title":"State"},"info":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Info"}},"type":"object","required":["task_id","state"],"title":"DocumentCreateTask"},"DocumentIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of document roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of document roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"DocumentIAMMemberRoleUpdate"},"DocumentIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","edit","query","remove_editor","remove_member","remove_owner","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the document."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"DocumentIAMPermissionTest"},"DocumentProcessingStatus":{"properties":{"group_id":{"type":"string","title":"Group Id"},"upload_count":{"type":"integer","title":"Upload Count"},"completed":{"type":"integer","title":"Completed"},"tasks":{"items":{"$ref":"#/components/schemas/DocumentProcessingTask"},"type":"array","title":"Tasks"}},"type":"object","required":["group_id","upload_count","completed","tasks"],"title":"DocumentProcessingStatus"},"DocumentProcessingTask":{"properties":{"task_id":{"type":"string","title":"Task Id"},"state":{"anyOf":[{},{"type":"null"}],"title":"State"},"info":{"anyOf":[{},{"type":"null"}],"title":"Info"}},"type":"object","required":["task_id","state","info"],"title":"DocumentProcessingTask"},"DocumentSource":{"type":"string","enum":["upload","gdrive","onedrive","web_scrape","notion","confluence","box","dropbox","sharepoint"],"title":"DocumentSource","description":"Source types for documents in the system."},"DocumentStatusResponse":{"properties":{"group_id":{"type":"string","title":"Group Id"},"task_count":{"type":"integer","title":"Task Count"},"tasks":{"items":{"$ref":"#/components/schemas/DocumentCreateTask"},"type":"array","title":"Tasks"}},"type":"object","required":["group_id","task_count","tasks"],"title":"DocumentStatusResponse"},"EffectiveModelExclusionsResponse":{"properties":{"organization_rules":{"items":{"$ref":"#/components/schemas/ModelExclusionRuleResponse"},"type":"array","title":"Organization Rules","description":"Exclusion rules set at organization level"},"project_rules":{"items":{"$ref":"#/components/schemas/ModelExclusionRuleResponse"},"type":"array","title":"Project Rules","description":"Exclusion rules set at project level"},"total_excluded_models":{"type":"integer","title":"Total Excluded Models","description":"Total number of active models excluded by all rules (org + project)"},"available_model_count":{"type":"integer","title":"Available Model Count","description":"Number of active models still available after all exclusions"}},"type":"object","required":["total_excluded_models","available_model_count"],"title":"EffectiveModelExclusionsResponse","description":"Response showing all exclusions with their sources.\n\nShows organization-level and project-level rules separately,\nplus computed impact on available models."},"EmailForwarderCreate":{"properties":{"name":{"type":"string","title":"Name","description":"A descriptive name for the Task Forwarder."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional details about the Task Forwarder's purpose or configuration."},"forwarder_type":{"type":"string","const":"email","title":"Forwarder Type","description":"Type of forwarder: email for email delivery","default":"email"},"config":{"$ref":"#/components/schemas/TaskForwarderEmailConfig","description":"Email configuration with recipient addresses and templates"},"config_sensitive":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config Sensitive","description":"Reserved for future sensitive email configuration"}},"type":"object","required":["name","config"],"title":"EmailForwarderCreate"},"EmailForwarderInDB":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The unique identifier of the Task Forwarder."},"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"The Project that the Task Forwarder belongs to."},"created":{"type":"string","title":"Created","description":"When the Task Forwarder was created."},"modified":{"type":"string","title":"Modified","description":"When the Task Forwarder was last updated."},"name":{"type":"string","title":"Name","description":"A descriptive name for the Task Forwarder."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional details about the Task Forwarder's purpose or configuration."},"forwarder_type":{"type":"string","const":"email","title":"Forwarder Type","description":"Type of forwarder: email for email delivery","default":"email"},"config":{"$ref":"#/components/schemas/TaskForwarderEmailConfig","description":"Email configuration with recipient addresses and templates"},"config_sensitive":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config Sensitive","description":"Reserved for future sensitive email configuration"}},"type":"object","required":["id","project_id","created","modified","name","config"],"title":"EmailForwarderInDB"},"EmailForwarderUpdate":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"A descriptive name for the Task Forwarder."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional details about the Task Forwarder's purpose or configuration."},"forwarder_type":{"type":"string","const":"email","title":"Forwarder Type","description":"Type of forwarder: email","default":"email"},"config":{"anyOf":[{"$ref":"#/components/schemas/TaskForwarderEmailConfig"},{"type":"null"}],"description":"Email configuration with recipient addresses and templates"},"config_sensitive":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config Sensitive","description":"Reserved for future sensitive email configuration"}},"type":"object","title":"EmailForwarderUpdate"},"EmptyErrorDetails":{"properties":{},"type":"object","title":"EmptyErrorDetails"},"EvalJudgeModelResponse":{"properties":{"name":{"type":"string","title":"Name"},"provider":{"type":"string","title":"Provider"}},"type":"object","required":["name","provider"],"title":"EvalJudgeModelResponse"},"EvalMetricComparison":{"properties":{"reference_avg":{"type":"number","title":"Reference Avg"},"candidate_avg":{"type":"number","title":"Candidate Avg"},"delta_pct":{"type":"number","title":"Delta Pct"}},"type":"object","required":["reference_avg","candidate_avg","delta_pct"],"title":"EvalMetricComparison"},"EvalResultMetrics":{"properties":{"reference":{"$ref":"#/components/schemas/EvalResultRunMetrics"},"candidate":{"anyOf":[{"$ref":"#/components/schemas/EvalResultRunMetrics"},{"type":"null"}]}},"type":"object","required":["reference"],"title":"EvalResultMetrics"},"EvalResultResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"eval_run_id":{"type":"string","format":"uuid","title":"Eval Run Id"},"reference_run_id":{"type":"string","format":"uuid","title":"Reference Run Id"},"candidate_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Candidate Run Id"},"verdict":{"anyOf":[{"$ref":"#/components/schemas/EvalVerdict"},{"type":"null"}]},"reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning"},"judge_input_tokens":{"type":"integer","title":"Judge Input Tokens"},"judge_output_tokens":{"type":"integer","title":"Judge Output Tokens"},"is_error":{"type":"boolean","title":"Is Error"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"created":{"type":"string","title":"Created"},"metrics":{"anyOf":[{"$ref":"#/components/schemas/EvalResultMetrics"},{"type":"null"}]}},"type":"object","required":["id","eval_run_id","reference_run_id","judge_input_tokens","judge_output_tokens","is_error","created"],"title":"EvalResultResponse"},"EvalResultRunMetrics":{"properties":{"total_tokens":{"type":"integer","title":"Total Tokens"},"charged_credits":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Charged Credits"},"llm_call_timing":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Llm Call Timing"}},"type":"object","required":["total_tokens","charged_credits","llm_call_timing"],"title":"EvalResultRunMetrics"},"EvalRunCreate":{"properties":{"candidate_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Candidate Revision Id"},"eval_set_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Eval Set Id"},"task_run_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":20},{"type":"null"}],"title":"Task Run Ids"},"last_n":{"anyOf":[{"type":"integer","maximum":20.0,"minimum":1.0},{"type":"null"}],"title":"Last N"},"judge_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Judge Model Id"}},"type":"object","title":"EvalRunCreate"},"EvalRunDetailResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_id":{"type":"string","format":"uuid","title":"Task Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"candidate_revision_id":{"type":"string","format":"uuid","title":"Candidate Revision Id"},"eval_set_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Eval Set Id"},"task_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Run Ids"},"status":{"$ref":"#/components/schemas/EvalStatus"},"pass_count":{"type":"integer","title":"Pass Count"},"fail_count":{"type":"integer","title":"Fail Count"},"error_count":{"type":"integer","title":"Error Count"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"created_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By User Id"},"judge_model":{"$ref":"#/components/schemas/EvalJudgeModelResponse"},"metrics":{"anyOf":[{"$ref":"#/components/schemas/EvalRunMetrics"},{"type":"null"}]},"results":{"items":{"$ref":"#/components/schemas/EvalResultResponse"},"type":"array","title":"Results","default":[]},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","readOnly":true}},"type":"object","required":["id","task_id","project_id","candidate_revision_id","task_run_ids","status","pass_count","fail_count","error_count","created","modified","judge_model","pass_rate"],"title":"EvalRunDetailResponse"},"EvalRunMetrics":{"properties":{"token_cost":{"anyOf":[{"$ref":"#/components/schemas/EvalMetricComparison"},{"type":"null"}]},"charged_credits":{"anyOf":[{"$ref":"#/components/schemas/EvalMetricComparison"},{"type":"null"}]},"llm_call_timing":{"anyOf":[{"$ref":"#/components/schemas/EvalMetricComparison"},{"type":"null"}]}},"type":"object","title":"EvalRunMetrics"},"EvalRunResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_id":{"type":"string","format":"uuid","title":"Task Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"candidate_revision_id":{"type":"string","format":"uuid","title":"Candidate Revision Id"},"eval_set_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Eval Set Id"},"task_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Run Ids"},"status":{"$ref":"#/components/schemas/EvalStatus"},"pass_count":{"type":"integer","title":"Pass Count"},"fail_count":{"type":"integer","title":"Fail Count"},"error_count":{"type":"integer","title":"Error Count"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"created_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By User Id"},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","readOnly":true}},"type":"object","required":["id","task_id","project_id","candidate_revision_id","task_run_ids","status","pass_count","fail_count","error_count","created","modified","pass_rate"],"title":"EvalRunResponse"},"EvalSetCreate":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Description"},"task_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":20,"minItems":1,"title":"Task Run Ids"}},"type":"object","required":["name","task_run_ids"],"title":"EvalSetCreate"},"EvalSetResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"task_id":{"type":"string","format":"uuid","title":"Task Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"task_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Run Ids"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"created_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By User Id"}},"type":"object","required":["id","name","task_id","project_id","task_run_ids","created","modified"],"title":"EvalSetResponse"},"EvalSetUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Description"},"task_run_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":20},{"type":"null"}],"title":"Task Run Ids"}},"type":"object","title":"EvalSetUpdate"},"EvalStatus":{"type":"string","enum":["pending","running","completed","failed"],"title":"EvalStatus"},"EvalVerdict":{"type":"string","enum":["pass","fail"],"title":"EvalVerdict"},"ExcludeModelByIdRequest":{"properties":{"model_id":{"type":"string","format":"uuid","title":"Model Id","description":"UUID of model to exclude"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason","description":"Reason for exclusion"}},"type":"object","required":["model_id"],"title":"ExcludeModelByIdRequest","description":"Request to exclude a specific model by ID"},"ExcludeModelByProviderRequest":{"properties":{"provider":{"type":"string","maxLength":100,"minLength":1,"title":"Provider","description":"Provider name (e.g., 'OpenAI', 'Anthropic', 'Meta')"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason","description":"Reason for exclusion"}},"type":"object","required":["provider"],"title":"ExcludeModelByProviderRequest","description":"Request to exclude all models from a provider"},"ExcludeModelByVendorRequest":{"properties":{"vendor":{"type":"string","maxLength":100,"minLength":1,"title":"Vendor","description":"Vendor name (e.g., 'openai', 'anthropic', 'google', 'groq')"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason","description":"Reason for exclusion"}},"type":"object","required":["vendor"],"title":"ExcludeModelByVendorRequest","description":"Request to exclude all models from a vendor"},"ExecutionSurface":{"type":"string","enum":["a2a","eval","gmail_inbox","internal_task_agent","internal_task_agent_approval_resume","mcp","schedule","slack","task_agent_api","task_agent_approval_resume","task_agent_task_tool","task_api","webhook"]},"FieldValidationErrorDetails":{"properties":{"field":{"type":"string","title":"Field"},"value":{"title":"Value"}},"type":"object","required":["field","value"],"title":"FieldValidationErrorDetails"},"FileInputMode":{"type":"string","enum":["none","image","pdf","image_or_pdf","any"],"title":"FileInputMode","description":"Defines what file types a task accepts for visual processing."},"GmailInboxTriggerCreate":{"properties":{"name":{"type":"string","maxLength":63,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/TriggerStatus","default":"enabled"},"label_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Label Ids"},"sender_filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/GmailSenderFilter"},"type":"array"},{"type":"null"}],"title":"Sender Filters"},"subject_contains":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Subject Contains"},"payload_mapping":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Mapping"},"target_type":{"$ref":"#/components/schemas/TriggerTargetType"},"target_id":{"type":"string","format":"uuid","title":"Target Id"},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"},"project_integration_id":{"type":"string","format":"uuid","title":"Project Integration Id"}},"additionalProperties":false,"type":"object","required":["name","target_type","target_id","project_integration_id"],"title":"GmailInboxTriggerCreate"},"GmailInboxTriggerListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"target_type":{"$ref":"#/components/schemas/TriggerTargetType"},"target_id":{"type":"string","format":"uuid","title":"Target Id"},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"},"trigger_type":{"type":"string","const":"gmail_inbox","title":"Trigger Type","default":"gmail_inbox"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/TriggerStatus"},"created":{"type":"string","title":"Created"},"project_integration_id":{"type":"string","format":"uuid","title":"Project Integration Id"},"integration_auth_principal_id":{"type":"string","format":"uuid","title":"Integration Auth Principal Id"},"email_address":{"type":"string","title":"Email Address"},"health_state":{"type":"string","enum":["healthy","degraded","unhealthy"],"title":"Health State","default":"healthy"},"health_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Health Reason"},"watch_status":{"anyOf":[{"$ref":"#/components/schemas/GmailMailboxWatchStatus"},{"type":"null"}]},"watch_expiration_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Watch Expiration At"}},"type":"object","required":["id","target_type","target_id","name","status","created","project_integration_id","integration_auth_principal_id","email_address"],"title":"GmailInboxTriggerListItem"},"GmailInboxTriggerResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"target_type":{"$ref":"#/components/schemas/TriggerTargetType"},"target_id":{"type":"string","format":"uuid","title":"Target Id"},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"},"trigger_type":{"type":"string","const":"gmail_inbox","title":"Trigger Type","default":"gmail_inbox"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/TriggerStatus"},"project_integration_id":{"type":"string","format":"uuid","title":"Project Integration Id"},"integration_auth_principal_id":{"type":"string","format":"uuid","title":"Integration Auth Principal Id"},"mailbox_watch_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Mailbox Watch Id"},"email_address":{"type":"string","title":"Email Address"},"label_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Label Ids"},"sender_filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/GmailSenderFilter"},"type":"array"},{"type":"null"}],"title":"Sender Filters"},"subject_contains":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Subject Contains"},"payload_mapping":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Mapping"},"health_state":{"type":"string","enum":["healthy","degraded","unhealthy"],"title":"Health State","default":"healthy"},"health_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Health Reason"},"watch_status":{"anyOf":[{"$ref":"#/components/schemas/GmailMailboxWatchStatus"},{"type":"null"}]},"watch_expiration_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Watch Expiration At"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"created_by_user_id":{"type":"string","format":"uuid","title":"Created By User Id"}},"type":"object","required":["id","target_type","target_id","name","status","project_integration_id","integration_auth_principal_id","email_address","created","modified","created_by_user_id"],"title":"GmailInboxTriggerResponse"},"GmailInboxTriggerUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":63,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Description"},"status":{"anyOf":[{"$ref":"#/components/schemas/TriggerStatus"},{"type":"null"}]},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"},"label_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Label Ids"},"sender_filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/GmailSenderFilter"},"type":"array"},{"type":"null"}],"title":"Sender Filters"},"subject_contains":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Subject Contains"},"payload_mapping":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Mapping"}},"type":"object","title":"GmailInboxTriggerUpdate"},"GmailMailboxWatchStatus":{"type":"string","enum":["pending","active","renewal_failed","reauth_required","resync_required","disabled"],"title":"GmailMailboxWatchStatus","description":"Lifecycle/health status for Gmail mailbox watches."},"GmailSenderFilter":{"properties":{"type":{"type":"string","enum":["email","domain","pattern"],"title":"Type"},"value":{"type":"string","maxLength":320,"minLength":1,"title":"Value"}},"type":"object","required":["type","value"],"title":"GmailSenderFilter"},"GmailTriggerEventDetailResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"gmail_inbox_trigger_id":{"type":"string","format":"uuid","title":"Gmail Inbox Trigger Id"},"gmail_notification_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Gmail Notification Id"},"gmail_message_id":{"type":"string","title":"Gmail Message Id"},"gmail_thread_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gmail Thread Id"},"history_id":{"type":"string","title":"History Id"},"email_address":{"type":"string","title":"Email Address"},"status":{"$ref":"#/components/schemas/TriggerEventStatus"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"task_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Run Id"},"task_agent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Run Id"},"received_at":{"type":"string","title":"Received At"},"processing_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"mapped_input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Mapped Input"}},"type":"object","required":["id","gmail_inbox_trigger_id","gmail_message_id","history_id","email_address","status","received_at"],"title":"GmailTriggerEventDetailResponse"},"GmailTriggerEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"gmail_inbox_trigger_id":{"type":"string","format":"uuid","title":"Gmail Inbox Trigger Id"},"gmail_notification_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Gmail Notification Id"},"gmail_message_id":{"type":"string","title":"Gmail Message Id"},"gmail_thread_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gmail Thread Id"},"history_id":{"type":"string","title":"History Id"},"email_address":{"type":"string","title":"Email Address"},"status":{"$ref":"#/components/schemas/TriggerEventStatus"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"task_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Run Id"},"task_agent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Run Id"},"received_at":{"type":"string","title":"Received At"},"processing_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["id","gmail_inbox_trigger_id","gmail_message_id","history_id","email_address","status","received_at"],"title":"GmailTriggerEventResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IAMMember":{"properties":{"member":{"type":"string","title":"Member","description":"The member identifier string, the format of which is '<subject_type>:<subject_id>'"},"roles":{"items":{"type":"string"},"type":"array","title":"Roles","description":"A list of roles that the member holds on an entity.\n\nSome entities, such as Organizations, may contain members that exist without any roles.","default":[]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The name of the member."},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url","description":"If avatar of the member, if it is supported by their subject type."},"total_subjects":{"type":"integer","title":"Total Subjects","description":"The total number of subjects that the member represents, which may be a value other than `1` if the member is not a User.","default":1}},"type":"object","required":["member"],"title":"IAMMember"},"IAMObjectErrorDetails":{"properties":{"type":{"type":"string","title":"Type"},"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"}},"type":"object","required":["type"],"title":"IAMObjectErrorDetails"},"IAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions"},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"IAMPermissionTest"},"InitialComposeSection":{"properties":{"position":{"type":"integer","title":"Position"},"title":{"type":"string","title":"Title"},"ideas":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Ideas"}},"type":"object","required":["position","title"],"title":"InitialComposeSection"},"InputConversationalGuardrailDefinition":{"properties":{"name":{"type":"string","enum":["prompt_policy","pii_policy"],"title":"Name"}},"type":"object","required":["name"],"title":"InputConversationalGuardrailDefinition"},"InputProcessor":{"properties":{"name":{"type":"string","title":"Input Processor Name","description":"The unique identifier/name of the input processor. Used to reference this processor in API calls.","examples":["url_fetcher"]},"description":{"type":"string","title":"Input Processor Description","description":"A human-readable description of what the input processor does.","examples":["Fetches the HTML content for the provided site and replaces the URL with the fetched content."]},"config_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Configuration Schema","description":"JSON Schema describing the available configuration options for this processor. Null if the processor does not have a configuration schema.","examples":[{"additionalProperties":false,"properties":{"max_results":{"default":5,"description":"Number of search results to return","maximum":100,"minimum":1,"type":"integer"}},"type":"object"}]}},"type":"object","required":["name","description"],"title":"InputProcessor","description":"Schema representing an input processor that can transform task inputs.","examples":[{"config_schema":{"properties":{"fetch_mode":{"default":"default","description":"How the URL should be fetched. Use 'default' for the standard fetch behavior or 'direct' to fetch the URL directly.","enum":["default","direct"],"type":"string"},"fallback_text":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Text to return if hosted fetching fails."}},"type":"object"},"description":"Fetches the HTML content for the provided site and replaces the URL with the fetched content.","name":"url_fetcher"}]},"IntegrationCapabilitySelector":{"properties":{"integration_type":{"type":"string","minLength":1,"title":"Integration Type","description":"Stable integration type identifier required by the skill."},"tool_name":{"type":"string","minLength":1,"title":"Tool Name","description":"Integration tool name required by the skill."}},"additionalProperties":false,"type":"object","required":["integration_type","tool_name"],"title":"IntegrationCapabilitySelector"},"IntegrationCatalogItemRead":{"properties":{"type":{"type":"string","enum":["google_sheets","google_docs","google_slides","google_calendar","google_gmail","slack","teams","xero"],"title":"Type"},"name":{"type":"string","title":"Name"},"description":{"type":"string","title":"Description"},"connection_scopes":{"items":{"$ref":"#/components/schemas/IntegrationConnectionScope"},"type":"array","title":"Connection Scopes"},"credential_policies":{"items":{"$ref":"#/components/schemas/IntegrationCredentialPolicy"},"type":"array","title":"Credential Policies"},"available_tools":{"items":{"$ref":"#/components/schemas/IntegrationCatalogToolRead"},"type":"array","title":"Available Tools"},"setup_instructions":{"type":"string","title":"Setup Instructions"}},"type":"object","required":["type","name","description","connection_scopes","credential_policies","available_tools","setup_instructions"],"title":"IntegrationCatalogItemRead"},"IntegrationCatalogToolRead":{"properties":{"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"default_selected":{"type":"boolean","title":"Default Selected","description":"Whether the tool is included when an integration attachment omits an explicit tool selection.","default":true}},"type":"object","required":["name"],"title":"IntegrationCatalogToolRead"},"IntegrationConnectionRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"auth_state":{"type":"string","enum":["connected","reauth_required","disconnected"],"title":"Auth State"},"auth_state_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth State Reason"},"connected_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Connected By User Id"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"type":"object","required":["id","auth_state","created","modified"],"title":"IntegrationConnectionRead"},"IntegrationConnectionScope":{"type":"string","enum":["user","project_default"]},"IntegrationConnectionStatusRead":{"properties":{"integration_id":{"type":"string","format":"uuid","title":"Integration Id"},"connection_scope":{"$ref":"#/components/schemas/IntegrationConnectionScope"},"connection":{"anyOf":[{"$ref":"#/components/schemas/IntegrationConnectionRead"},{"type":"null"}]}},"type":"object","required":["integration_id","connection_scope","connection"],"title":"IntegrationConnectionStatusRead"},"IntegrationCredentialPolicy":{"type":"string","enum":["invoker","fixed_connection","project_default"]},"IntegrationSkillDependency":{"properties":{"id":{"type":"string","minLength":1,"title":"Id","description":"Stable identifier for this dependency within the capability set."},"type":{"type":"string","const":"integration","title":"Type"},"required":{"type":"boolean","title":"Required","description":"Whether the dependency must be resolvable for the skill to function."},"selector":{"$ref":"#/components/schemas/IntegrationCapabilitySelector"},"credential_policy":{"anyOf":[{"$ref":"#/components/schemas/IntegrationCredentialPolicy"},{"type":"null"}],"description":"Credential policy required by this Integration dependency."}},"additionalProperties":false,"type":"object","required":["id","type","required","selector"],"title":"IntegrationSkillDependency"},"IntegrationToolInvocationRead":{"properties":{"integration_id":{"type":"string","title":"Integration Id","description":"ProjectIntegration ID as a UUID string."},"integration_name":{"type":"string","title":"Integration Name","description":"Display name of the integration."},"integration_type":{"type":"string","title":"Integration Type","description":"Integration type identifier."},"integration_tool_id":{"type":"string","title":"Integration Tool Id","description":"IntegrationTool ID as a UUID string."},"tool_name":{"type":"string","title":"Tool Name","description":"Runtime name of the integration tool."},"principal_type":{"type":"string","title":"Principal Type","description":"Principal type used for the invocation."},"is_error":{"type":"boolean","title":"Is Error","default":false},"duration_ms":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Duration Ms","description":"Integration tool execution duration in milliseconds."},"error_message":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Error Message","description":"Short error summary for failed integration tool invocations."}},"type":"object","required":["integration_id","integration_name","integration_type","integration_tool_id","tool_name","principal_type"],"title":"IntegrationToolInvocationRead","description":"Schema for an individual integration tool invocation during a run."},"IntegrationToolRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"tool_name":{"type":"string","title":"Tool Name"},"tool_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Description"},"tool_input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Input Schema"},"safe_tool_name":{"type":"string","title":"Safe Tool Name"},"enabled":{"type":"boolean","title":"Enabled"},"default_selected":{"type":"boolean","title":"Default Selected","description":"Whether the tool is exposed when a TaskAgent attaches this integration without an explicit allowed_tool_ids selection."},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"type":"object","required":["id","name","tool_name","safe_tool_name","enabled","default_selected","created","modified"],"title":"IntegrationToolRead"},"InvalidMemberErrorDetails":{"properties":{"resource":{"anyOf":[{"$ref":"#/components/schemas/IAMObjectErrorDetails"},{"type":"null"}]},"subject":{"anyOf":[{"$ref":"#/components/schemas/IAMObjectErrorDetails"},{"type":"null"}]}},"type":"object","title":"InvalidMemberErrorDetails"},"InvalidMemberErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["INVALID_MEMBER"],"const":"INVALID_MEMBER","title":"Reason","description":"The machine-readable error reason."},"invalidMemberError":{"$ref":"#/components/schemas/InvalidMemberErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","invalidMemberError"],"title":"InvalidMemberErrorPayload"},"InvalidMemberErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/InvalidMemberErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"InvalidMemberErrorResponse"},"InvalidRoleErrorDetails":{"properties":{"resource":{"anyOf":[{"$ref":"#/components/schemas/IAMObjectErrorDetails"},{"type":"null"}]},"role":{"type":"string","title":"Role"}},"type":"object","required":["role"],"title":"InvalidRoleErrorDetails"},"InvalidRoleErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["INVALID_ROLE"],"const":"INVALID_ROLE","title":"Reason","description":"The machine-readable error reason."},"invalidRoleError":{"$ref":"#/components/schemas/InvalidRoleErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","invalidRoleError"],"title":"InvalidRoleErrorPayload"},"InvalidRoleErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/InvalidRoleErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"InvalidRoleErrorResponse"},"InvalidSubjectTypeErrorDetails":{"properties":{"subject":{"anyOf":[{"$ref":"#/components/schemas/IAMObjectErrorDetails"},{"type":"null"}]}},"type":"object","title":"InvalidSubjectTypeErrorDetails"},"InvalidSubjectTypeErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["INVALID_SUBJECT_TYPE"],"const":"INVALID_SUBJECT_TYPE","title":"Reason","description":"The machine-readable error reason."},"invalidSubjectTypeError":{"$ref":"#/components/schemas/InvalidSubjectTypeErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","invalidSubjectTypeError"],"title":"InvalidSubjectTypeErrorPayload"},"InvalidSubjectTypeErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/InvalidSubjectTypeErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"InvalidSubjectTypeErrorResponse"},"LLMModel":{"properties":{"provider":{"type":"string","title":"Provider","description":"The company that produces the LLM (e.g., OpenAI, Anthropic, Meta).","examples":["OpenAI"]},"vendor":{"type":"string","title":"Vendor","description":"The service provider or platform hosting the model (e.g., OpenAI, Azure, Groq).","examples":["openai"]},"name":{"type":"string","title":"Name","description":"The model's reference name used for API calls.","examples":["gpt-4-turbo-preview"]},"alias":{"type":"string","title":"Alias","description":"Human-readable name for the model.","examples":["GPT-4 Turbo"]},"description":{"type":"string","title":"Description","description":"Detailed description of the model's capabilities, context window, and knowledge cutoff.","examples":["Latest GPT-4 model with 128k context window and knowledge cutoff of December 2023."]},"supports_vision":{"type":"boolean","title":"Supports Vision","description":"Whether the model can process and analyze images.","examples":[true]},"supports_image_output":{"type":"boolean","title":"Supports Image Output","description":"Whether the model can generate images as output.","default":false,"examples":[false]},"supports_pdf_vision":{"type":"boolean","title":"Supports Pdf Vision","description":"Whether the model can process PDFs as visual input.","default":false,"examples":[true]},"supports_tool_calling":{"type":"boolean","title":"Supports Tool Calling","description":"Whether the model supports tool calling APIs.","default":false,"examples":[true]},"supports_context_caching":{"type":"boolean","title":"Supports Context Caching","description":"Whether the model supports provider-native context caching.","default":false,"examples":[true]},"price":{"anyOf":[{"$ref":"#/components/schemas/LLMModelPriceTier"},{"type":"null"}],"description":"Coarse model price tier for selector comparison.","examples":["average"]},"speed":{"anyOf":[{"$ref":"#/components/schemas/LLMModelSpeedTier"},{"type":"null"}],"description":"Coarse model inference speed tier for selector comparison.","examples":["fast"]},"knowledge_cutoff":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Knowledge Cutoff","description":"Date of the model's most recent training data, when known.","examples":["2024-10-01"]},"pdf_vision_config":{"anyOf":[{"$ref":"#/components/schemas/PDFVisionConfig"},{"type":"null"}],"description":"Configuration limits for PDF vision processing."},"max_context_window":{"type":"integer","minimum":0.0,"title":"Max Context Window","description":"Maximum number of tokens the model can process in a single request.","examples":[128000]},"model_params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Model Params","description":"JSON Schema defining allowed model parameters for this model. Each parameter name maps to a JSON Schema specification defining its type, constraints, and validation rules.","examples":[{"max_tokens":{"description":"Maximum number of tokens to generate","maximum":4096,"minimum":1,"type":"integer"},"temperature":{"description":"Controls randomness in outputs","maximum":2.0,"minimum":0.0,"type":"number"}}]},"created":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created"},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"},"id":{"type":"string","format":"uuid","title":"Id"},"replaced_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Replaced By"},"retired":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Retired"},"llm_model_comments":{"items":{"$ref":"#/components/schemas/LLMModelComment"},"type":"array","title":"Llm Model Comments","default":[]}},"type":"object","required":["provider","vendor","name","alias","description","supports_vision","max_context_window","id"],"title":"LLMModel","example":{"alias":"GPT-4 Turbo","created":"2024-01-16T13:33:25.247662","description":"Latest GPT-4 model with 128k context window and knowledge cutoff of December 2023.","id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","knowledge_cutoff":"2023-12-01","max_context_window":128000,"model_params":{"temperature":{"description":"Controls randomness in outputs","maximum":2.0,"minimum":0.0,"type":"number"}},"modified":"2024-01-16T13:33:25.247662","name":"gpt-4-turbo-preview","price":"average","provider":"OpenAI","replaced_by":"0190a234-8dc6-6d08-aea9-928fcecad8f2","retired":"2024-01-16T13:33:25.247662","speed":"fast","supports_context_caching":false,"supports_image_output":false,"supports_vision":true,"vendor":"openai"}},"LLMModelComment":{"properties":{"title":{"type":"string","maxLength":255,"title":"Title","description":"Brief title for the comment.","examples":["Performance Issue"]},"description":{"type":"string","title":"Description","description":"Detailed description of the comment or observation.","examples":["Model exhibits inconsistent response quality with complex reasoning tasks."]},"active":{"type":"boolean","title":"Active","description":"Whether this comment is currently active/relevant.","default":true,"examples":[true]},"created":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created","description":"When this comment was created."},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified","description":"When this comment was last modified."},"id":{"type":"string","format":"uuid","title":"Id"},"llm_model_id":{"type":"string","format":"uuid","title":"Llm Model Id"}},"type":"object","required":["title","description","id","llm_model_id"],"title":"LLMModelComment","example":{"active":true,"created":"2024-01-16T13:33:25.247662","description":"Model exhibits inconsistent response quality with complex reasoning tasks.","id":"0190a234-8dc6-6d08-aea9-928fcecad8f5","llm_model_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","modified":"2024-01-16T13:33:25.247662","title":"Performance Issue"}},"LLMModelPriceTier":{"type":"string","enum":["cheap","average","expensive"],"title":"LLMModelPriceTier"},"LLMModelSpeedTier":{"type":"string","enum":["standard","fast","ultra fast"],"title":"LLMModelSpeedTier"},"MalformedResourceIdentifierErrorDetails":{"properties":{"field":{"type":"string","title":"Field"},"value":{"title":"Value"},"expected_format":{"type":"string","title":"Expected Format"}},"type":"object","required":["field","value","expected_format"],"title":"MalformedResourceIdentifierErrorDetails"},"MalformedResourceIdentifierErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["MALFORMED_RESOURCE_IDENTIFIER"],"const":"MALFORMED_RESOURCE_IDENTIFIER","title":"Reason","description":"The machine-readable error reason."},"malformedResourceIdentifierError":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","malformedResourceIdentifierError"],"title":"MalformedResourceIdentifierErrorPayload"},"MalformedResourceIdentifierErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/MalformedResourceIdentifierErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"MalformedResourceIdentifierErrorResponse"},"McpDiscoveredTool":{"properties":{"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema"}},"type":"object","required":["name"],"title":"McpDiscoveredTool"},"McpRun":{"properties":{"method":{"type":"string","maxLength":64,"minLength":1,"title":"Method","description":"MCP method name"},"request_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Request Id","description":"JSON-RPC request ID"},"protocol_version":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Protocol Version","description":"MCP protocol version"},"request":{"additionalProperties":true,"type":"object","title":"Request","description":"Request data"},"response":{"additionalProperties":true,"type":"object","title":"Response","description":"Response data"},"duration_ms":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Duration Ms","description":"Duration in milliseconds"},"sse_event":{"type":"boolean","title":"Sse Event","description":"Whether this is a server-sent event","default":false},"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the MCP run"},"mcp_server_id":{"type":"string","format":"uuid","title":"Mcp Server Id","description":"MCP server ID"},"created":{"type":"string","title":"Created","description":"Timestamp when the MCP run was created"},"modified":{"type":"string","title":"Modified","description":"Timestamp when the MCP run was last modified"}},"type":"object","required":["method","request","response","id","mcp_server_id","created","modified"],"title":"McpRun","description":"Complete MCP Run schema for API responses."},"McpRunCreate":{"properties":{"method":{"type":"string","maxLength":64,"minLength":1,"title":"Method","description":"MCP method name"},"request_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Request Id","description":"JSON-RPC request ID"},"protocol_version":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Protocol Version","description":"MCP protocol version"},"request":{"additionalProperties":true,"type":"object","title":"Request","description":"Request data"},"response":{"additionalProperties":true,"type":"object","title":"Response","description":"Response data"},"duration_ms":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Duration Ms","description":"Duration in milliseconds"},"sse_event":{"type":"boolean","title":"Sse Event","description":"Whether this is a server-sent event","default":false},"mcp_server_id":{"type":"string","format":"uuid","title":"Mcp Server Id","description":"MCP server ID"}},"type":"object","required":["method","request","response","mcp_server_id"],"title":"McpRunCreate","description":"Attributes to create an instance of McpRun."},"McpServer":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"title":"Name","description":"MCP server name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the MCP server"},"url":{"type":"string","maxLength":255,"minLength":1,"title":"Url","description":"Root URL of the MCP server"},"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the MCP server"},"short_id":{"type":"string","maxLength":8,"title":"Short Id","description":"Short identifier for the MCP server"},"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"Project ID this MCP server belongs to"},"syncd":{"type":"boolean","title":"Syncd","description":"Whether the server has been sync'd to external proxy"},"created":{"type":"string","title":"Created","description":"Timestamp when the MCP server was created"},"modified":{"type":"string","title":"Modified","description":"Timestamp when the MCP server was last modified"}},"type":"object","required":["name","url","id","short_id","project_id","syncd","created","modified"],"title":"McpServer","description":"Complete MCP Server schema for API responses."},"McpServerCapabilitySelector":{"properties":{"mcp_server_slug":{"type":"string","minLength":1,"title":"Mcp Server Slug","description":"Canonical MCP server slug required by the skill."}},"additionalProperties":false,"type":"object","required":["mcp_server_slug"],"title":"McpServerCapabilitySelector"},"McpServerCreate":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"title":"Name","description":"MCP server name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the MCP server"},"url":{"type":"string","maxLength":255,"minLength":1,"title":"Url","description":"Root URL of the MCP server"}},"type":"object","required":["name","url"],"title":"McpServerCreate","description":"Attributes a user can submit to create an instance of McpServer."},"McpServerDiscoveryRequest":{"properties":{"server_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Server Url"},"auth_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Session Id"},"api_key":{"anyOf":[{"type":"string","format":"password","writeOnly":true},{"type":"null"}],"title":"Api Key"},"api_key_strategy":{"anyOf":[{"$ref":"#/components/schemas/TaskMcpAuthStrategy"},{"type":"null"}]},"api_key_header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Header Name"}},"additionalProperties":false,"type":"object","required":["server_url"],"title":"McpServerDiscoveryRequest"},"McpServerDiscoveryResponse":{"properties":{"server_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Server Url"},"canonical_resource":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Canonical Resource"},"tools":{"items":{"$ref":"#/components/schemas/McpDiscoveredTool"},"type":"array","title":"Tools"},"transport":{"$ref":"#/components/schemas/TaskMcpTransport","default":"streamable_http"}},"type":"object","required":["server_url","canonical_resource","tools"],"title":"McpServerDiscoveryResponse"},"McpServerSkillDependency":{"properties":{"id":{"type":"string","minLength":1,"title":"Id","description":"Stable identifier for this dependency within the capability set."},"type":{"type":"string","const":"mcp_server","title":"Type"},"required":{"type":"boolean","title":"Required","description":"Whether the dependency must be resolvable for the skill to function."},"selector":{"$ref":"#/components/schemas/McpServerCapabilitySelector"}},"additionalProperties":false,"type":"object","required":["id","type","required","selector"],"title":"McpServerSkillDependency"},"McpServerUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name","description":"MCP server name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the MCP server"},"url":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Url","description":"Root URL of the MCP server"}},"type":"object","title":"McpServerUpdate","description":"Attributes a user can update."},"McpToolCapabilitySelector":{"properties":{"mcp_server_slug":{"type":"string","minLength":1,"title":"Mcp Server Slug","description":"Canonical MCP server slug required by the skill."},"tool_name":{"type":"string","minLength":1,"title":"Tool Name","description":"MCP tool name required by the skill."}},"additionalProperties":false,"type":"object","required":["mcp_server_slug","tool_name"],"title":"McpToolCapabilitySelector"},"McpToolInvocationRead":{"properties":{"server_id":{"type":"string","title":"Server Id","description":"TaskMcpServer ID as a UUID string."},"server_name":{"type":"string","title":"Server Name","description":"Name of the MCP server."},"tool_name":{"type":"string","title":"Tool Name","description":"Name of the MCP tool that was called."},"is_error":{"type":"boolean","title":"Is Error","default":false},"duration_ms":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Duration Ms","description":"MCP tool execution duration in milliseconds."},"error_message":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Error Message","description":"Short error summary for failed MCP tool invocations."}},"type":"object","required":["server_id","server_name","tool_name"],"title":"McpToolInvocationRead","description":"Schema for an individual MCP tool invocation during a run."},"McpToolSkillDependency":{"properties":{"id":{"type":"string","minLength":1,"title":"Id","description":"Stable identifier for this dependency within the capability set."},"type":{"type":"string","const":"mcp_tool","title":"Type"},"required":{"type":"boolean","title":"Required","description":"Whether the dependency must be resolvable for the skill to function."},"selector":{"$ref":"#/components/schemas/McpToolCapabilitySelector"}},"additionalProperties":false,"type":"object","required":["id","type","required","selector"],"title":"McpToolSkillDependency"},"Mcp_ServerIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of mcp_server roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of mcp_server roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"Mcp ServerIAMMemberRoleUpdate"},"Mcp_ServerIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","edit","remove_editor","remove_member","remove_owner","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the mcp_server."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"Mcp ServerIAMPermissionTest"},"MissingAuthenticationErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["MISSING_AUTHENTICATION"],"const":"MISSING_AUTHENTICATION","title":"Reason","description":"The machine-readable error reason."},"missingAuthenticationError":{"$ref":"#/components/schemas/EmptyErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","missingAuthenticationError"],"title":"MissingAuthenticationErrorPayload"},"MissingAuthenticationErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/MissingAuthenticationErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"MissingAuthenticationErrorResponse"},"ModelConfiguration":{"properties":{"exclusion_rules":{"items":{"$ref":"#/components/schemas/ModelExclusionRule"},"type":"array","title":"Exclusion Rules","description":"Rules defining which models are excluded"},"default_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Default Model Id","description":"Default model to use (future functionality)"},"model_preferences":{"additionalProperties":{"additionalProperties":true,"type":"object"},"type":"object","title":"Model Preferences","description":"Per-model configuration preferences (future functionality)"}},"type":"object","title":"ModelConfiguration","description":"Model management configuration for organizations and projects.\n\nStores exclusion rules and future configuration options like\ndefault models and per-model preferences."},"ModelExclusionMutationResponse":{"properties":{"status":{"type":"string","const":"excluded","title":"Status","default":"excluded"},"rule_type":{"type":"string","enum":["model_id","provider","vendor"],"title":"Rule Type"},"model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Model Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"vendor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor"}},"type":"object","required":["rule_type"],"title":"ModelExclusionMutationResponse","description":"Response returned after adding a model exclusion rule."},"ModelExclusionRemovalResponse":{"properties":{"status":{"type":"string","const":"removed","title":"Status","default":"removed"},"rule_type":{"type":"string","enum":["model_id","provider","vendor"],"title":"Rule Type"},"value":{"type":"string","title":"Value"}},"type":"object","required":["rule_type","value"],"title":"ModelExclusionRemovalResponse","description":"Response returned after removing a model exclusion rule."},"ModelExclusionRule":{"properties":{"rule_type":{"type":"string","enum":["model_id","provider","vendor"],"title":"Rule Type","description":"Type of exclusion rule"},"model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Model Id","description":"Specific model ID to exclude"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider","description":"Provider name to exclude all models from"},"vendor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor","description":"Vendor name to exclude all models from"},"excluded_at":{"type":"string","format":"date-time","title":"Excluded At","description":"When this exclusion was created"},"excluded_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Excluded By User Id","description":"User who created this exclusion"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason","description":"Reason for exclusion"}},"type":"object","required":["rule_type","excluded_at"],"title":"ModelExclusionRule","description":"A rule defining which models to exclude.\n\nRules can exclude by:\n- model_id: Specific model\n- provider: All models from a provider (e.g., \"OpenAI\", \"Anthropic\")\n- vendor: All models from a vendor (e.g., \"openai\", \"google\", \"groq\")"},"ModelExclusionRuleResponse":{"properties":{"rule_type":{"type":"string","enum":["model_id","provider","vendor"],"title":"Rule Type"},"model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Model Id"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider"},"vendor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vendor"},"excluded_at":{"type":"string","format":"date-time","title":"Excluded At"},"excluded_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Excluded By User Id"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"affected_model_count":{"type":"integer","title":"Affected Model Count","description":"Number of active models currently affected by this rule"},"affected_models":{"items":{"type":"string"},"type":"array","title":"Affected Models","description":"Names (aliases) of affected models (limited to first 10)"}},"type":"object","required":["rule_type","excluded_at","affected_model_count"],"title":"ModelExclusionRuleResponse","description":"Response showing an exclusion rule with computed impact.\n\nIncludes which models are currently affected by this rule."},"MultipleRolesNotAllowedErrorDetails":{"properties":{"resource":{"anyOf":[{"$ref":"#/components/schemas/IAMObjectErrorDetails"},{"type":"null"}]},"roles":{"items":{"type":"string"},"type":"array","title":"Roles"}},"type":"object","required":["roles"],"title":"MultipleRolesNotAllowedErrorDetails"},"MultipleRolesNotAllowedErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["MULTIPLE_ROLES_NOT_ALLOWED"],"const":"MULTIPLE_ROLES_NOT_ALLOWED","title":"Reason","description":"The machine-readable error reason."},"multipleRolesNotAllowedError":{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","multipleRolesNotAllowedError"],"title":"MultipleRolesNotAllowedErrorPayload"},"MultipleRolesNotAllowedErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/MultipleRolesNotAllowedErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"MultipleRolesNotAllowedErrorResponse"},"NoDocumentContentExtractedErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["NO_DOCUMENT_CONTENT_EXTRACTED"],"const":"NO_DOCUMENT_CONTENT_EXTRACTED","title":"Reason","description":"The machine-readable error reason."},"noDocumentContentExtractedError":{"$ref":"#/components/schemas/FieldValidationErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","noDocumentContentExtractedError"],"title":"NoDocumentContentExtractedErrorPayload"},"NoDocumentContentExtractedErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/NoDocumentContentExtractedErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"NoDocumentContentExtractedErrorResponse"},"NoUsableDocumentContentErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["NO_USABLE_DOCUMENT_CONTENT"],"const":"NO_USABLE_DOCUMENT_CONTENT","title":"Reason","description":"The machine-readable error reason."},"noUsableDocumentContentError":{"$ref":"#/components/schemas/FieldValidationErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","noUsableDocumentContentError"],"title":"NoUsableDocumentContentErrorPayload"},"NoUsableDocumentContentErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/NoUsableDocumentContentErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"NoUsableDocumentContentErrorResponse"},"OAuthClient":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the OAuth client.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"name":{"type":"string","title":"Name","description":"Human-readable name for the OAuth client.","examples":["Production API Client","Web App OAuth Client"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description explaining the client's purpose and usage.","examples":["OAuth client for production API access","Authentication for web application"]},"redirect_uris":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Redirect Uris","description":"List of authorized redirect URIs for OAuth flows requiring user interaction.\nRequired for authorization code and implicit flows.\nMust be exact matches when used.\nMust use HTTPS in production (except for localhost).","examples":[["https://app.example.com/oauth/callback"],["http://localhost:3000/callback","https://staging.example.com/oauth/callback"]]},"grant_types":{"anyOf":[{"items":{"$ref":"#/components/schemas/OAuthClientGrantType"},"type":"array"},{"type":"null"}],"title":"Grant Types","description":"OAuth 2.0 grant types enabled for this client.\n- client_credentials: For server-to-server API access\n- authorization_code: For web and mobile apps\n- refresh_token: For maintaining long-term access\n- implicit: Legacy flow, not recommended for new applications","examples":[["client_credentials","refresh_token"],["authorization_code","refresh_token"]]},"client_id":{"type":"string","format":"uuid","title":"Client Id","description":"Unique identifier used to identify the client with the authorization server.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f2"]},"client_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Secret","description":"Secret key used to authenticate the client.\nOnly shown once upon creation.\nMust be stored securely.\nRequired for confidential clients (e.g., server applications).","examples":["client_secret_shown_only_once"]},"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"ID of the project this OAuth client belongs to.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f3"]},"token_endpoint_auth_method":{"type":"string","enum":["client_secret_basic","client_secret_post","none"],"title":"Token Endpoint Auth Method","description":"Authentication method enabled for the client:\n- client_secret_basic: Client ID and secret sent in HTTP headers\n- client_secret_post: Client ID and secret sent in request body\n- none: No client authentication (required for public clients using PKCE)","default":"client_secret_basic","examples":["client_secret_basic","client_secret_post","none"]},"pkce_required":{"type":"boolean","title":"Pkce Required","description":"Whether PKCE (Proof Key for Code Exchange) is required for this client.\nWhen enabled, authorization code flows must include code_challenge and code_verifier.\nRecommended for public clients (mobile apps, SPAs) and enhances security for all clients.","default":false,"examples":[true,false]},"pkce_challenge_method":{"anyOf":[{"$ref":"#/components/schemas/OAuthClientPKCEChallengeMethod"},{"type":"null"}],"description":"PKCE code challenge method when PKCE is enabled.\n- S256: SHA256 hash of code verifier (recommended and secure)\n- plain: Plain text code verifier (not recommended, only for testing)","default":"S256","examples":["S256"]},"created":{"type":"string","title":"Created","description":"Timestamp when the OAuth client was created.","examples":["2024-01-15T09:30:00Z"]},"modified":{"type":"string","title":"Modified","description":"Timestamp when the OAuth client was last modified.","examples":["2024-01-15T09:30:00Z"]},"deleted":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deleted","description":"Timestamp when the OAuth client was deleted, if applicable.","examples":["2024-01-15T09:30:00Z"]}},"type":"object","required":["id","name","client_id","project_id","created","modified"],"title":"OAuthClient"},"OAuthClientGrantType":{"type":"string","enum":["client_credentials","refresh_token","implicit","authorization_code"],"title":"OAuthClientGrantType","description":"OAuth 2.0 grant types supported by the client."},"OAuthClientPKCEChallengeMethod":{"type":"string","enum":["S256","plain"],"title":"OAuthClientPKCEChallengeMethod","description":"PKCE code challenge methods supported."},"OAuthClientRegenerateSecretResponse":{"properties":{"client_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Secret","description":"Generated client secret.\nIMPORTANT: This is the only time the secret will be shown.\nStore it securely.","examples":["client_secret_shown_only_once"]}},"type":"object","title":"OAuthClientRegenerateSecretResponse"},"OAuthClientUpdate":{"properties":{"redirect_uris":{"anyOf":[{"items":{"type":"string"},"type":"array","minItems":1},{"type":"null"}],"title":"Redirect Uris","description":"Updated list of authorized redirect URIs.\nAll existing URIs will be replaced with this list.","examples":[["https://app.example.com/oauth/callback","https://backup.example.com/callback"]]},"grant_types":{"anyOf":[{"items":{"$ref":"#/components/schemas/OAuthClientGrantType"},"type":"array"},{"type":"null"}],"title":"Grant Types","description":"Updated list of enabled grant types.\nAll existing grant types will be replaced with this list.","examples":[["authorization_code","refresh_token"],["client_credentials","refresh_token"]]},"token_endpoint_auth_method":{"anyOf":[{"type":"string","enum":["client_secret_basic","client_secret_post","none"]},{"type":"null"}],"title":"Token Endpoint Auth Method","description":"Updated authentication method for the token endpoint.","examples":["client_secret_basic","client_secret_post","none"]},"pkce_required":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Pkce Required","description":"Whether to require PKCE for authorization code flows.\nIMPORTANT: Only applicable when 'authorization_code' is included in grant_types.\nSetting to True enhances security, especially for public clients.","examples":[true,false]},"pkce_challenge_method":{"anyOf":[{"$ref":"#/components/schemas/OAuthClientPKCEChallengeMethod"},{"type":"null"}],"description":"PKCE code challenge method.\nOnly applies when PKCE is required.","examples":["S256"]}},"type":"object","title":"OAuthClientUpdate"},"Org":{"properties":{"name":{"type":"string","title":"Name"},"contact_email":{"type":"string","format":"email","title":"Contact Email"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"public_metadata":{"additionalProperties":{"type":"string"},"type":"object","title":"Public Metadata","default":{}},"low_credit_alerts":{"type":"boolean","title":"Low Credit Alerts","default":false},"usage_based_pricing_enabled":{"type":"boolean","title":"Usage Based Pricing Enabled","default":false},"plan":{"$ref":"#/components/schemas/StripePlan","default":"trial"},"plan_status":{"$ref":"#/components/schemas/PlanStatus","default":"active"},"plan_interval":{"anyOf":[{"$ref":"#/components/schemas/PlanInterval"},{"type":"null"}]},"pending_plan":{"anyOf":[{"$ref":"#/components/schemas/StripePlan"},{"type":"null"}]},"pending_plan_interval":{"anyOf":[{"$ref":"#/components/schemas/PlanInterval"},{"type":"null"}]},"pending_plan_date":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Pending Plan Date"},"trial_ends_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Trial Ends At"},"grace_period_ends_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Grace Period Ends At"},"auto_topup_config":{"additionalProperties":true,"type":"object","title":"Auto Topup Config","default":{}},"id":{"type":"string","format":"uuid","title":"Id"},"account":{"anyOf":[{"$ref":"#/components/schemas/Account"},{"type":"null"}]}},"type":"object","required":["name","contact_email","id"],"title":"Org"},"OrgCreate":{"properties":{"name":{"type":"string","pattern":"^[a-zA-Z0-9\\-_ ]+$","title":"Name","description":"Organization name"},"contact_email":{"type":"string","format":"email","title":"Contact Email"}},"type":"object","required":["name","contact_email"],"title":"OrgCreate"},"OrgInviteShow":{"type":"string","enum":["all","pending","accepted"],"title":"OrgInviteShow"},"OrgInviteWithProjectRoles":{"properties":{"email_address":{"type":"string","format":"email","title":"Email Address"},"roles":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Roles"},"project_roles":{"anyOf":[{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},{"type":"null"}],"title":"Project Roles"}},"type":"object","required":["email_address"],"title":"OrgInviteWithProjectRoles","examples":[{"email_address":"user@example.com","project_roles":{"01234567-89ab-cdef-0123-456789abcdef":["task_creator"],"fedcba98-7654-3210-fedc-ba9876543210":["task_viewer"]}}]},"OrgMembership":{"type":"string","enum":["active","joinable","joinable_by_domain","joinable_by_invite"],"title":"OrgMembership"},"OrgUpdate":{"properties":{"name":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9\\-_ ]+$"},{"type":"null"}],"title":"Name","description":"Organization name"},"contact_email":{"anyOf":[{"type":"string","format":"email"},{"type":"null"}],"title":"Contact Email"},"low_credit_alerts":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Low Credit Alerts"},"usage_based_pricing_enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Usage Based Pricing Enabled"}},"type":"object","title":"OrgUpdate"},"OrganizationDomain":{"properties":{"domain":{"type":"string","title":"Domain"},"id":{"type":"string","format":"uuid","title":"Id"},"status":{"type":"string","enum":["unverified","verified"],"title":"Status"}},"type":"object","required":["domain","id","status"],"title":"OrganizationDomain"},"OrganizationDomainCreate":{"properties":{"domain":{"type":"string","title":"Domain"}},"type":"object","required":["domain"],"title":"OrganizationDomainCreate"},"OrganizationIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of organization roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of organization roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"OrganizationIAMMemberRoleUpdate"},"OrganizationIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","create_project","edit","remove_editor","remove_member","remove_owner","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the organization."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"OrganizationIAMPermissionTest"},"OrganizationInvite":{"properties":{"email_address":{"type":"string","format":"email","title":"Email Address"},"roles":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Roles"},"project_roles":{"anyOf":[{"additionalProperties":{"items":{"type":"string"},"type":"array"},"type":"object"},{"type":"null"}],"title":"Project Roles"},"id":{"type":"string","format":"uuid","title":"Id"}},"type":"object","required":["email_address","id"],"title":"OrganizationInvite","examples":[{"email_address":"user@example.com","project_roles":{"01234567-89ab-cdef-0123-456789abcdef":["task_creator"],"fedcba98-7654-3210-fedc-ba9876543210":["task_viewer"]}}]},"OrganizationInviteAlreadyExistsErrorDetails":{"properties":{"organization_id":{"type":"string","title":"Organization Id"},"email_address":{"type":"string","title":"Email Address"}},"type":"object","required":["organization_id","email_address"],"title":"OrganizationInviteAlreadyExistsErrorDetails"},"OrganizationInviteAlreadyExistsErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["ORGANIZATION_INVITE_ALREADY_EXISTS"],"const":"ORGANIZATION_INVITE_ALREADY_EXISTS","title":"Reason","description":"The machine-readable error reason."},"organizationInviteAlreadyExistsError":{"$ref":"#/components/schemas/OrganizationInviteAlreadyExistsErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","organizationInviteAlreadyExistsError"],"title":"OrganizationInviteAlreadyExistsErrorPayload"},"OrganizationInviteAlreadyExistsErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/OrganizationInviteAlreadyExistsErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"OrganizationInviteAlreadyExistsErrorResponse"},"OrganizationMemberAlreadyExistsErrorDetails":{"properties":{"organization_id":{"type":"string","title":"Organization Id"},"member_id":{"type":"string","title":"Member Id"}},"type":"object","required":["organization_id","member_id"],"title":"OrganizationMemberAlreadyExistsErrorDetails"},"OrganizationMemberAlreadyExistsErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["ORGANIZATION_MEMBER_ALREADY_EXISTS"],"const":"ORGANIZATION_MEMBER_ALREADY_EXISTS","title":"Reason","description":"The machine-readable error reason."},"organizationMemberAlreadyExistsError":{"$ref":"#/components/schemas/OrganizationMemberAlreadyExistsErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","organizationMemberAlreadyExistsError"],"title":"OrganizationMemberAlreadyExistsErrorPayload"},"OrganizationMemberAlreadyExistsErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/OrganizationMemberAlreadyExistsErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"OrganizationMemberAlreadyExistsErrorResponse"},"OutputConversationalGuardrailDefinition":{"properties":{"name":{"type":"string","const":"source_validation","title":"Name"}},"type":"object","required":["name"],"title":"OutputConversationalGuardrailDefinition"},"OutputFilter":{"type":"string","enum":["image"],"title":"OutputFilter","description":"Output capability filter for model listing."},"OutputModality":{"type":"string","enum":["json","image","audio","pdf","text","csv"],"title":"OutputModality","description":"Output modality types for tasks."},"PDFVisionConfig":{"properties":{"max_file_size_mb":{"type":"integer","title":"Max File Size Mb","description":"Maximum PDF file size in megabytes","default":50},"max_pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Pages","description":"Maximum number of pages (None = unlimited)"},"max_visual_pages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Visual Pages","description":"Maximum pages processed visually. Used by Claude which only visually processes first 100 pages."}},"type":"object","title":"PDFVisionConfig","description":"Configuration for PDF vision capabilities."},"PaginatedResultSet_AuditEventListItem_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/AuditEventListItem"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[AuditEventListItem]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_AvailableSkillRead_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/AvailableSkillRead"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[AvailableSkillRead]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_ChatDocumentEmbeddingRecord_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/ChatDocumentEmbeddingRecord"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[ChatDocumentEmbeddingRecord]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_ChatDocument_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/ChatDocument"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[ChatDocument]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_Collection_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/Collection"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[Collection]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_DatasourceSyncRun_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/DatasourceSyncRun"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[DatasourceSyncRun]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_EvalRunResponse_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/EvalRunResponse"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[EvalRunResponse]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_EvalSetResponse_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/EvalSetResponse"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[EvalSetResponse]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_GmailTriggerEventResponse_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/GmailTriggerEventResponse"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[GmailTriggerEventResponse]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_IAMMember_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/IAMMember"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[IAMMember]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_McpRun_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/McpRun"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[McpRun]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_McpServer_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/McpServer"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[McpServer]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_OAuthClient_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/OAuthClient"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[OAuthClient]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_Org_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/Org"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[Org]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_OrganizationDomain_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/OrganizationDomain"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[OrganizationDomain]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_OrganizationInvite_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/OrganizationInvite"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[OrganizationInvite]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_PartnerOrganizationSummary_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/PartnerOrganizationSummary"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[PartnerOrganizationSummary]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_Partner_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/Partner"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[Partner]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_ProjectSkillRead_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/ProjectSkillRead"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[ProjectSkillRead]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_ProjectTaskAgentApprovalRequestRead_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/ProjectTaskAgentApprovalRequestRead"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[ProjectTaskAgentApprovalRequestRead]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_Project_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/Project"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[Project]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_ReportingGroup_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/ReportingGroup"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[ReportingGroup]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_ScheduleTriggerEventResponse_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/ScheduleTriggerEventResponse"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[ScheduleTriggerEventResponse]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_SkillRead_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/SkillRead"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[SkillRead]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_Tag_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/Tag"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[Tag]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskAgentApprovalRequestRead_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskAgentApprovalRequestRead"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskAgentApprovalRequestRead]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskAgentEvalRunResponse_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskAgentEvalRunResponse"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskAgentEvalRunResponse]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskAgentEvalSetResponse_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskAgentEvalSetResponse"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskAgentEvalSetResponse]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskAgentRead_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskAgentRead"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskAgentRead]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskAgentRunRead_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskAgentRunRead"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskAgentRunRead]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskAgentShare_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskAgentShare"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskAgentShare]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskForwarder_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskForwarder"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskForwarder]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskMcpServer_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskMcpServer"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskMcpServer]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskMcpTool_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskMcpTool"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskMcpTool]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskRecentRunsSummary_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskRecentRunsSummary"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskRecentRunsSummary]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskRun_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskRun"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskRun]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_TaskShare_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/TaskShare"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[TaskShare]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginatedResultSet_Task_":{"properties":{"pagination":{"anyOf":[{"$ref":"#/components/schemas/PaginationDetails"},{"type":"null"}],"description":"Contains pagination information for the result set."},"results":{"items":{"$ref":"#/components/schemas/Task"},"type":"array","title":"Results","description":"The list of items returned for the current page."}},"type":"object","required":["results"],"title":"PaginatedResultSet[Task]","example":{"pagination":{"has_next":true,"next_cursor":"019097c5-5560-05b5-4a48-5197a269683b","page_limit":100}}},"PaginationDetails":{"properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"A token used to retrieve the next page of results. If `null`, there are no more results."},"has_next":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Next","description":"Indicates whether there are more results available in the next page.","default":false},"page_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Limit","description":"The maximum number of items returned per page.","default":0}},"type":"object","title":"PaginationDetails"},"Partner":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"created":{"type":"string","format":"date-time","title":"Created"},"modified":{"type":"string","format":"date-time","title":"Modified"}},"type":"object","required":["id","name","description","avatar_url","created","modified"],"title":"Partner"},"PartnerCreate":{"properties":{"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"}},"type":"object","required":["name"],"title":"PartnerCreate"},"PartnerOrganizationSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"created":{"type":"string","format":"date-time","title":"Created"}},"type":"object","required":["id","name","created"],"title":"PartnerOrganizationSummary"},"PartnerUpdate":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description"}},"type":"object","title":"PartnerUpdate"},"PermissionCheckFailedErrorDetails":{"properties":{"subject":{"anyOf":[{"$ref":"#/components/schemas/IAMObjectErrorDetails"},{"type":"null"}]},"resource":{"anyOf":[{"$ref":"#/components/schemas/IAMObjectErrorDetails"},{"type":"null"}]},"permission":{"type":"string","title":"Permission"}},"type":"object","required":["permission"],"title":"PermissionCheckFailedErrorDetails"},"PermissionCheckFailedErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["PERMISSION_CHECK_FAILED"],"const":"PERMISSION_CHECK_FAILED","title":"Reason","description":"The machine-readable error reason."},"permissionCheckFailedError":{"$ref":"#/components/schemas/PermissionCheckFailedErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","permissionCheckFailedError"],"title":"PermissionCheckFailedErrorPayload"},"PermissionCheckFailedErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/PermissionCheckFailedErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"PermissionCheckFailedErrorResponse"},"PhaseTimingEntry":{"properties":{"phase":{"type":"string","enum":["llm_inference","task_tool_execution","mcp_tool_execution","integration_tool_execution","skill_activation","memory_compaction"],"title":"Phase"},"start_ms":{"type":"integer","minimum":0.0,"title":"Start Ms","description":"Phase start offset in milliseconds."},"end_ms":{"type":"integer","minimum":0.0,"title":"End Ms","description":"Phase end offset in milliseconds."},"call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Id","description":"ADK function_call_id for tool phases."},"task_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Run Id","description":"TaskRun ID for task tool execution phases."},"tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Name","description":"MCP tool name for MCP execution phases."},"server_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Server Name","description":"MCP server name for MCP execution phases."},"integration_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Integration Name","description":"Integration name for integration execution phases."},"trigger":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trigger","description":"Trigger for memory compaction phases."},"compaction_event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compaction Event Id","description":"ADK compaction event ID for memory compaction phases."},"input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Input Tokens","description":"Input tokens used by the memory compaction summarizer."},"output_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Output Tokens","description":"Output tokens produced by the memory compaction summarizer."},"total_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Tokens","description":"Total tokens used by the memory compaction summarizer."},"token_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Token Threshold","description":"Configured token threshold for memory compaction phases."},"event_retention_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Event Retention Size","description":"Configured ADK event retention size for token compaction."}},"type":"object","required":["phase","start_ms","end_ms"],"title":"PhaseTimingEntry","description":"Schema for an orchestration timing phase within a run."},"PlanInterval":{"type":"string","enum":["monthly","yearly"],"title":"PlanInterval"},"PlanStatus":{"type":"string","enum":["active","grace","cancelling","cancelled"],"title":"PlanStatus"},"Project":{"properties":{"name":{"type":"string","title":"Name"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"id":{"type":"string","format":"uuid","title":"Id"},"org_id":{"type":"string","format":"uuid","title":"Org Id"},"tasks_oauth_client_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tasks Oauth Client Id"},"public_routing_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Routing Key"},"agent_access_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Access Key"},"deleted":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Deleted"}},"type":"object","required":["name","id","org_id"],"title":"Project"},"ProjectConfig":{"properties":{"llm":{"type":"string","title":"Llm","default":"gpt-3.5-turbo"},"temperature":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Temperature","default":0.5},"knn":{"type":"integer","exclusiveMinimum":0.0,"title":"Knn","default":4},"chat_system_commands":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Chat System Commands"},"chat_guardrails":{"anyOf":[{"$ref":"#/components/schemas/ConversationalGuardrails"},{"type":"null"}]},"query_expansion":{"type":"boolean","title":"Query Expansion","description":"Enable query expansion. Uses an LLM to generate multiple rephrasing of the original query for better broad spectrum vector retrieval","default":false},"models_config":{"$ref":"#/components/schemas/ModelConfiguration","description":"Model management configuration"}},"type":"object","title":"ProjectConfig"},"ProjectConfigUpdate":{"properties":{"llm":{"type":"string","title":"Llm","default":"gpt-3.5-turbo"},"temperature":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Temperature","default":0.5},"knn":{"type":"integer","exclusiveMinimum":0.0,"title":"Knn","default":4},"chat_system_commands":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Chat System Commands"},"chat_guardrails":{"anyOf":[{"$ref":"#/components/schemas/ConversationalGuardrails"},{"type":"null"}]},"query_expansion":{"type":"boolean","title":"Query Expansion","description":"Enable query expansion. Uses an LLM to generate multiple rephrasing of the original query for better broad spectrum vector retrieval","default":false}},"additionalProperties":false,"type":"object","title":"ProjectConfigUpdate","description":"Fields clients may update through the generic project config endpoint."},"ProjectCreate":{"properties":{"name":{"type":"string","pattern":"^[a-zA-Z0-9\\-_ ]+$","title":"Name","description":"Project name"}},"type":"object","required":["name"],"title":"ProjectCreate"},"ProjectIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["data_creator","data_editor","data_viewer","editor","mcp_server_creator","oauth_client_creator","owner","task_creator","task_mcp_server_creator","task_runner","viewer"]},"type":"array","title":"Add","description":"A list of project roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["data_creator","data_editor","data_viewer","editor","mcp_server_creator","oauth_client_creator","owner","task_creator","task_mcp_server_creator","task_runner","viewer"]},"type":"array","title":"Remove","description":"A list of project roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"ProjectIAMMemberRoleUpdate"},"ProjectIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","collections_edit","collections_view","create_chat","create_collection","create_compose","create_datasource_connection","create_document","create_mcp_server","create_oauth_client","create_project_integration","create_skill","create_task","create_task_agent","create_task_forwarder","create_task_mcp_server","datasource_connections_edit","datasource_connections_view","documents_edit","documents_view","edit","edit_data","list_documents","query_data","remove_editor","remove_member","remove_owner","run_task","run_task_agent","view","view_data","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the project."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"ProjectIAMPermissionTest"},"ProjectIntegrationCreate":{"properties":{"type":{"type":"string","enum":["google_sheets","google_docs","google_slides","google_calendar","google_gmail","slack","teams","xero"],"title":"Type"},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config","description":"Reserved for provider-specific config. Google integrations ignore this in v1. Slack may accept {\"slack_installation_id\": \"<uuid>\"} to link an existing active Slack installation. Teams ignores create-time config and is linked after creation from the Teams setup tab. Xero rejects create-time config because its tenant routing metadata is written by the OAuth callback."}},"type":"object","required":["type"],"title":"ProjectIntegrationCreate"},"ProjectIntegrationRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"type":{"type":"string","enum":["google_sheets","google_docs","google_slides","google_calendar","google_gmail","slack","teams","xero"],"title":"Type"},"name":{"type":"string","title":"Name"},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config"},"tools":{"items":{"$ref":"#/components/schemas/IntegrationToolRead"},"type":"array","title":"Tools","default":[]},"setup_instructions":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Setup Instructions"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"type":"object","required":["id","project_id","type","name","created","modified"],"title":"ProjectIntegrationRead"},"ProjectSkillContentRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"display_name":{"type":"string","title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License"},"compatibility":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compatibility"},"source":{"$ref":"#/components/schemas/SkillSourceRead"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"active_revision":{"anyOf":[{"$ref":"#/components/schemas/ProjectSkillRevisionContent"},{"type":"null"}]}},"type":"object","required":["id","slug","display_name","description","license","compatibility","source","tags","active_revision"],"title":"ProjectSkillContentRead"},"ProjectSkillCreate":{"properties":{"display_name":{"type":"string","maxLength":255,"title":"Display Name","description":"Human-readable name of the skill.","examples":["Code Review Assistant"]},"description":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"title":"Description","description":"Short description shown in the skill catalog."},"license":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"License","description":"Optional license string for the skill."},"compatibility":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Compatibility","description":"Optional compatibility notes for the skill."},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug","description":"Stable lowercase kebab-case identifier for the skill.","examples":["code-review"]},"instructions":{"type":"string","title":"Instructions","description":"The primary instructions for this skill."},"reference_docs":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Reference Docs","description":"Optional named reference files bundled with the skill."},"assets":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Assets","description":"Optional named asset files bundled with the skill."},"skill_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Skill Metadata","description":"Optional ADK skill metadata for the initial revision."},"capabilities":{"anyOf":[{"$ref":"#/components/schemas/SkillCapabilities"},{"type":"null"}],"description":"Optional typed capability contract for the initial revision."}},"type":"object","required":["display_name","instructions"],"title":"ProjectSkillCreate","description":"Schema for creating a project-scoped skill and its initial revision."},"ProjectSkillRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"display_name":{"type":"string","title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License"},"compatibility":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compatibility"},"source":{"$ref":"#/components/schemas/SkillSourceRead"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"has_active_revision":{"type":"boolean","title":"Has Active Revision"},"has_capabilities":{"type":"boolean","title":"Has Capabilities"},"requires_prerequisites":{"type":"boolean","title":"Requires Prerequisites"},"active_revision":{"anyOf":[{"$ref":"#/components/schemas/SkillRevisionSummary"},{"type":"null"}]},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"created_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By User Id"}},"type":"object","required":["id","slug","display_name","description","license","compatibility","source","tags","has_active_revision","has_capabilities","requires_prerequisites","active_revision","created","modified","project_id","created_by_user_id"],"title":"ProjectSkillRead"},"ProjectSkillRevisionContent":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"skill_id":{"type":"string","format":"uuid","title":"Skill Id"},"instructions":{"type":"string","title":"Instructions"},"skill_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Skill Metadata"},"capabilities":{"anyOf":[{"$ref":"#/components/schemas/SkillCapabilities"},{"type":"null"}]},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Annotation"},"created":{"type":"string","title":"Created"},"reference_files":{"items":{"type":"string"},"type":"array","title":"Reference Files"},"asset_files":{"items":{"type":"string"},"type":"array","title":"Asset Files"},"reference_file_contents":{"items":{"$ref":"#/components/schemas/SkillRevisionFileContent"},"type":"array","title":"Reference File Contents"},"asset_file_contents":{"items":{"$ref":"#/components/schemas/SkillRevisionFileContent"},"type":"array","title":"Asset File Contents"},"script_files":{"items":{"type":"string"},"type":"array","title":"Script Files","default":[]}},"type":"object","required":["id","skill_id","instructions","skill_metadata","capabilities","annotation","created","reference_files","asset_files"],"title":"ProjectSkillRevisionContent"},"ProjectSkillRevisionCreate":{"properties":{"instructions":{"type":"string","title":"Instructions","description":"The primary instructions for this revision."},"reference_docs":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Reference Docs","description":"Optional named reference files bundled with this revision."},"assets":{"anyOf":[{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}],"title":"Assets","description":"Optional named asset files bundled with this revision."},"skill_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Skill Metadata","description":"Optional ADK skill metadata for this revision."},"capabilities":{"anyOf":[{"$ref":"#/components/schemas/SkillCapabilities"},{"type":"null"}],"description":"Optional typed capability contract for this revision."},"annotation":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Annotation","description":"Optional human note describing this revision."},"activate":{"type":"boolean","title":"Activate","description":"Whether to immediately activate this revision.","default":true}},"type":"object","required":["instructions"],"title":"ProjectSkillRevisionCreate","description":"Schema for creating a new project-scoped skill revision."},"ProjectSkillUpdate":{"properties":{"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"display_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Display Name"},"description":{"anyOf":[{"type":"string","maxLength":1024},{"type":"null"}],"title":"Description"},"license":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"License"},"compatibility":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Compatibility"}},"type":"object","title":"ProjectSkillUpdate","description":"Schema for updating project-scoped skill metadata."},"ProjectTaskAgentApprovalRequestRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"task_agent_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Agent Name"},"task_agent_revision_id":{"type":"string","format":"uuid","title":"Task Agent Revision Id"},"task_agent_run_id":{"type":"string","format":"uuid","title":"Task Agent Run Id"},"session_id":{"type":"string","title":"Session Id"},"adk_session_user_id":{"type":"string","title":"Adk Session User Id"},"invocation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invocation Id"},"function_call_id":{"type":"string","title":"Function Call Id"},"adk_event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Adk Event Id"},"requested_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Requested By User Id"},"requested_by_actor_type":{"$ref":"#/components/schemas/TaskAgentApprovalActorType"},"decided_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Decided By User Id"},"requester_is_decider":{"type":"boolean","title":"Requester Is Decider","default":false},"tool_action_control_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tool Action Control Id"},"action_mode_snapshot":{"type":"string","title":"Action Mode Snapshot"},"tool_type":{"$ref":"#/components/schemas/TaskAgentToolSource"},"tool_name":{"type":"string","title":"Tool Name"},"status":{"$ref":"#/components/schemas/TaskAgentApprovalRequestStatus"},"decision":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentApprovalDecision"},{"type":"null"}]},"decision_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision Note"},"created":{"type":"string","title":"Created"},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"},"decided_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decided At"},"expires_at":{"type":"string","title":"Expires At"}},"type":"object","required":["id","project_id","task_agent_id","task_agent_revision_id","task_agent_run_id","session_id","adk_session_user_id","function_call_id","requested_by_actor_type","action_mode_snapshot","tool_type","tool_name","status","created","expires_at"],"title":"ProjectTaskAgentApprovalRequestRead","description":"Compact approval request row for project-level TaskAgent approval lists."},"ProjectTaskAgentTimingReport":{"properties":{"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"Unique identifier of the Project."},"date_range":{"additionalProperties":{"type":"string"},"type":"object","title":"Date Range","description":"Time period covered by the report."},"aggregation":{"type":"string","enum":["hour","day"],"title":"Aggregation","description":"Time bucket granularity used for the report."},"data":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentTimingBucket"},"type":"object","title":"Data","description":"Average duration and visible run counts for each aggregation bucket."},"total_runs":{"type":"integer","minimum":0.0,"title":"Total Runs","description":"Total number of visible runs included in the report."}},"type":"object","required":["project_id","date_range","aggregation","data","total_runs"],"title":"ProjectTaskAgentTimingReport","description":"Aggregate run timing report across visible TaskAgents in a project."},"ProjectTaskAgentUsageReport":{"properties":{"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"Unique identifier of the Project."},"date_range":{"additionalProperties":{"type":"string"},"type":"object","title":"Date Range","description":"Time period covered by the report."},"aggregation":{"type":"string","enum":["day","week"],"title":"Aggregation","description":"Time bucket granularity used for the report."},"status":{"$ref":"#/components/schemas/UsageReportStatus","description":"Run outcome filter applied to the report."},"data":{"additionalProperties":{"type":"integer"},"type":"object","title":"Data","description":"Visible run counts for each aggregation bucket."},"total_runs":{"type":"integer","minimum":0.0,"title":"Total Runs","description":"Total number of visible runs included in the report."}},"type":"object","required":["project_id","date_range","aggregation","status","data","total_runs"],"title":"ProjectTaskAgentUsageReport","description":"Aggregate visible run counts over time across TaskAgents in a project."},"ProjectTaskRecentRunSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The unique identifier of the Task Run."},"status":{"type":"string","enum":["success","error"],"title":"Status","description":"Compact run outcome derived from is_error."},"created":{"type":"string","title":"Created","description":"The timestamp when the Task Run was created."}},"type":"object","required":["id","status","created"],"title":"ProjectTaskRecentRunSummary"},"ProjectTaskTimingBucket":{"properties":{"avg_llm_call_timing":{"type":"number","title":"Avg Llm Call Timing","description":"Average LLM call timing across all visible project task runs in the bucket."},"total_task_runs":{"type":"integer","title":"Total Task Runs","description":"Number of visible task runs in the bucket."}},"type":"object","required":["avg_llm_call_timing","total_task_runs"],"title":"ProjectTaskTimingBucket"},"ProjectTaskTimingReport":{"properties":{"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"The unique identifier of the Project."},"date_range":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object","title":"Date Range","description":"The time range for the report, with start and end timestamps."},"aggregation":{"type":"string","enum":["hour","day"],"title":"Aggregation","description":"The time interval for data aggregation."},"data":{"additionalProperties":{"$ref":"#/components/schemas/ProjectTaskTimingBucket"},"type":"object","title":"Data","description":"Timing data for each time bucket."},"total_task_runs":{"type":"integer","title":"Total Task Runs","description":"Total visible task runs across the full reporting window."}},"type":"object","required":["project_id","date_range","aggregation","data","total_task_runs"],"title":"ProjectTaskTimingReport"},"ProjectTaskUsageReport":{"properties":{"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"The unique identifier of the Project."},"date_range":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object","title":"Date Range","description":"The time range for the report, with start and end timestamps."},"aggregation":{"type":"string","enum":["day","week"],"title":"Aggregation","description":"The time interval for data aggregation."},"status":{"$ref":"#/components/schemas/UsageReportStatus","description":"Run outcome filter applied to this usage report."},"data":{"additionalProperties":{"type":"integer"},"type":"object","title":"Data","description":"Visible task-run counts for each aggregation bucket."},"total_runs":{"type":"integer","title":"Total Runs","description":"Total visible task runs across the reporting window."}},"type":"object","required":["project_id","date_range","aggregation","status","data","total_runs"],"title":"ProjectTaskUsageReport"},"ProjectUpdate":{"properties":{"name":{"anyOf":[{"type":"string","pattern":"^[a-zA-Z0-9\\-_ ]+$"},{"type":"null"}],"title":"Name","description":"Project name"}},"type":"object","title":"ProjectUpdate"},"ProjectWithDatasources":{"properties":{"name":{"type":"string","title":"Name"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"id":{"type":"string","format":"uuid","title":"Id"},"org_id":{"type":"string","format":"uuid","title":"Org Id"},"tasks_oauth_client_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tasks Oauth Client Id"},"public_routing_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Public Routing Key"},"agent_access_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Access Key"},"deleted":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Deleted"},"datasource_connections":{"items":{"$ref":"#/components/schemas/DatasourceConnectionPublic"},"type":"array","title":"Datasource Connections","default":[]}},"type":"object","required":["name","id","org_id"],"title":"ProjectWithDatasources"},"Project_IntegrationIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of project_integration roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of project_integration roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"Project IntegrationIAMMemberRoleUpdate"},"Project_IntegrationIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","delete","edit","remove_editor","remove_member","remove_owner","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the project_integration."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"Project IntegrationIAMPermissionTest"},"RegisteredToolCapabilitySelector":{"properties":{"kind":{"type":"string","const":"registered_key","title":"Kind","description":"Selector kind for a platform-registered tool capability.","default":"registered_key"},"value":{"type":"string","minLength":1,"title":"Value","description":"Stable registered tool key for the required capability."}},"additionalProperties":false,"type":"object","required":["value"],"title":"RegisteredToolCapabilitySelector"},"RegisteredToolSkillDependency":{"properties":{"id":{"type":"string","minLength":1,"title":"Id","description":"Stable identifier for this dependency within the capability set."},"type":{"type":"string","const":"registered_tool","title":"Type"},"required":{"type":"boolean","title":"Required","description":"Whether the dependency must be resolvable for the skill to function."},"selector":{"$ref":"#/components/schemas/RegisteredToolCapabilitySelector"}},"additionalProperties":false,"type":"object","required":["id","type","required","selector"],"title":"RegisteredToolSkillDependency"},"ReportingGroup":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"title":"Name","description":"Name of the reporting group"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional description"},"id":{"type":"string","format":"uuid","title":"Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"type":"object","required":["name","id","project_id","created","modified"],"title":"ReportingGroup","description":"Schema for reporting group responses."},"ReportingGroupCreate":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"title":"Name","description":"Name of the reporting group"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional description"}},"type":"object","required":["name"],"title":"ReportingGroupCreate","description":"Schema for creating a new reporting group."},"ReportingGroupUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Name","description":"Name of the reporting group"},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Description","description":"Optional description"}},"type":"object","title":"ReportingGroupUpdate","description":"Schema for updating an existing reporting group."},"ResourceNotFoundErrorPayload":{"properties":{"message":{"type":"string","title":"Message","description":"Human readable representation of the error"},"reason":{"type":"string","enum":["RESOURCE_NOT_FOUND"],"const":"RESOURCE_NOT_FOUND","title":"Reason","description":"The machine-readable error reason."},"resourceNotFoundError":{"$ref":"#/components/schemas/FieldValidationErrorDetails","description":"Metadata detailing more information about the error."}},"type":"object","required":["message","reason","resourceNotFoundError"],"title":"ResourceNotFoundErrorPayload"},"ResourceNotFoundErrorResponse":{"properties":{"detail":{"$ref":"#/components/schemas/ResourceNotFoundErrorPayload","description":"The error payload."}},"type":"object","required":["detail"],"title":"ResourceNotFoundErrorResponse"},"ScheduleTriggerCreate":{"properties":{"name":{"type":"string","maxLength":63,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/TriggerStatus","default":"enabled"},"cron_expression":{"type":"string","maxLength":255,"title":"Cron Expression"},"timezone":{"type":"string","maxLength":63,"title":"Timezone","default":"UTC"},"task_input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Task Input"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"target_type":{"$ref":"#/components/schemas/TriggerTargetType"},"target_id":{"type":"string","format":"uuid","title":"Target Id"},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"}},"type":"object","required":["name","cron_expression","target_type","target_id"],"title":"ScheduleTriggerCreate"},"ScheduleTriggerEventDetailResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"schedule_trigger_id":{"type":"string","format":"uuid","title":"Schedule Trigger Id"},"scheduled_time":{"type":"string","title":"Scheduled Time"},"received_at":{"type":"string","title":"Received At"},"processing_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"status":{"type":"string","title":"Status"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"task_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Run Id"},"task_agent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Run Id"},"task_input_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Task Input Snapshot"}},"type":"object","required":["id","schedule_trigger_id","scheduled_time","received_at","status"],"title":"ScheduleTriggerEventDetailResponse"},"ScheduleTriggerEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"schedule_trigger_id":{"type":"string","format":"uuid","title":"Schedule Trigger Id"},"scheduled_time":{"type":"string","title":"Scheduled Time"},"received_at":{"type":"string","title":"Received At"},"processing_started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Processing Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"status":{"type":"string","title":"Status"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"task_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Run Id"},"task_agent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Run Id"}},"type":"object","required":["id","schedule_trigger_id","scheduled_time","received_at","status"],"title":"ScheduleTriggerEventResponse"},"ScheduleTriggerListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"target_type":{"$ref":"#/components/schemas/TriggerTargetType"},"target_id":{"type":"string","format":"uuid","title":"Target Id"},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"},"trigger_type":{"type":"string","const":"schedule","title":"Trigger Type","default":"schedule"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/TriggerStatus"},"created":{"type":"string","title":"Created"},"cron_expression":{"type":"string","title":"Cron Expression"},"timezone":{"type":"string","title":"Timezone"},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Run At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["id","target_type","target_id","name","status","created","cron_expression","timezone"],"title":"ScheduleTriggerListItem"},"ScheduleTriggerResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"target_type":{"$ref":"#/components/schemas/TriggerTargetType"},"target_id":{"type":"string","format":"uuid","title":"Target Id"},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"},"trigger_type":{"type":"string","const":"schedule","title":"Trigger Type","default":"schedule"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/TriggerStatus"},"cron_expression":{"type":"string","title":"Cron Expression"},"timezone":{"type":"string","title":"Timezone"},"task_input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Task Input"},"next_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Run At"},"last_run_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Run At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"created_by_user_id":{"type":"string","format":"uuid","title":"Created By User Id"}},"type":"object","required":["id","target_type","target_id","name","status","cron_expression","timezone","created","modified","created_by_user_id"],"title":"ScheduleTriggerResponse"},"ScheduleTriggerUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":63,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Description"},"status":{"anyOf":[{"$ref":"#/components/schemas/TriggerStatus"},{"type":"null"}]},"cron_expression":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Cron Expression"},"timezone":{"anyOf":[{"type":"string","maxLength":63},{"type":"null"}],"title":"Timezone"},"task_input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Task Input"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"}},"type":"object","title":"ScheduleTriggerUpdate"},"SiteScrapeRequest":{"properties":{"urls":{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array","title":"Urls"},"max_crawl_depth":{"type":"integer","maximum":7.0,"title":"Max Crawl Depth","default":3}},"type":"object","required":["urls"],"title":"SiteScrapeRequest"},"SkillActivateRevisionRequest":{"properties":{"revision_id":{"type":"string","format":"uuid","title":"Revision Id"}},"type":"object","required":["revision_id"],"title":"SkillActivateRevisionRequest"},"SkillActivationRead":{"properties":{"skill_id":{"type":"string","title":"Skill Id","description":"Skill ID as a UUID string."},"skill_slug":{"type":"string","title":"Skill Slug"},"skill_display_name":{"type":"string","title":"Skill Display Name"},"skill_revision_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Skill Revision Id"},"activated":{"type":"boolean","title":"Activated","description":"Whether the LLM loaded this skill during the run."}},"type":"object","required":["skill_id","skill_slug","skill_display_name","activated"],"title":"SkillActivationRead","description":"Schema for a declarative skill activation during a run."},"SkillCapabilities":{"properties":{"schema_version":{"type":"string","const":"1.0.0","title":"Schema Version","description":"Versioned schema identifier for the capability contract."},"dependencies":{"items":{"oneOf":[{"$ref":"#/components/schemas/RegisteredToolSkillDependency"},{"$ref":"#/components/schemas/IntegrationSkillDependency"},{"$ref":"#/components/schemas/McpServerSkillDependency"},{"$ref":"#/components/schemas/McpToolSkillDependency"}],"discriminator":{"propertyName":"type","mapping":{"integration":"#/components/schemas/IntegrationSkillDependency","mcp_server":"#/components/schemas/McpServerSkillDependency","mcp_tool":"#/components/schemas/McpToolSkillDependency","registered_tool":"#/components/schemas/RegisteredToolSkillDependency"}}},"type":"array","title":"Dependencies","description":"Declarative dependency requirements for this skill revision."}},"additionalProperties":false,"type":"object","required":["schema_version","dependencies"],"title":"SkillCapabilities"},"SkillContentRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"display_name":{"type":"string","title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License"},"compatibility":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compatibility"},"source":{"$ref":"#/components/schemas/SkillSourceRead"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"active_revision":{"anyOf":[{"$ref":"#/components/schemas/SkillRevisionContent"},{"type":"null"}]}},"type":"object","required":["id","slug","display_name","description","license","compatibility","source","tags","active_revision"],"title":"SkillContentRead"},"SkillIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of skill roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of skill roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"SkillIAMMemberRoleUpdate"},"SkillIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","edit","remove_editor","remove_member","remove_owner","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the skill."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"SkillIAMPermissionTest"},"SkillRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"display_name":{"type":"string","title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"license":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"License"},"compatibility":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Compatibility"},"source":{"$ref":"#/components/schemas/SkillSourceRead"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"has_active_revision":{"type":"boolean","title":"Has Active Revision"},"has_capabilities":{"type":"boolean","title":"Has Capabilities"},"requires_prerequisites":{"type":"boolean","title":"Requires Prerequisites"},"active_revision":{"anyOf":[{"$ref":"#/components/schemas/SkillRevisionSummary"},{"type":"null"}]},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"type":"object","required":["id","slug","display_name","description","license","compatibility","source","tags","has_active_revision","has_capabilities","requires_prerequisites","active_revision","created","modified"],"title":"SkillRead"},"SkillRevisionContent":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"skill_id":{"type":"string","format":"uuid","title":"Skill Id"},"instructions":{"type":"string","title":"Instructions"},"skill_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Skill Metadata"},"capabilities":{"anyOf":[{"$ref":"#/components/schemas/SkillCapabilities"},{"type":"null"}]},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Annotation"},"created":{"type":"string","title":"Created"},"reference_files":{"items":{"type":"string"},"type":"array","title":"Reference Files"},"asset_files":{"items":{"type":"string"},"type":"array","title":"Asset Files"},"reference_file_contents":{"items":{"$ref":"#/components/schemas/SkillRevisionFileContent"},"type":"array","title":"Reference File Contents"},"asset_file_contents":{"items":{"$ref":"#/components/schemas/SkillRevisionFileContent"},"type":"array","title":"Asset File Contents"},"script_files":{"items":{"type":"string"},"type":"array","title":"Script Files","default":[]}},"type":"object","required":["id","skill_id","instructions","skill_metadata","capabilities","annotation","created","reference_files","asset_files"],"title":"SkillRevisionContent"},"SkillRevisionFileContent":{"properties":{"path":{"type":"string","title":"Path"},"content":{"type":"string","title":"Content"},"size_bytes":{"type":"integer","minimum":0.0,"title":"Size Bytes","description":"The UTF-8 encoded file size in bytes."},"size_kb":{"type":"number","minimum":0.0,"title":"Size Kb","description":"The UTF-8 encoded file size in kilobytes, rounded to 2 decimals."}},"type":"object","required":["path","content","size_bytes","size_kb"],"title":"SkillRevisionFileContent"},"SkillRevisionListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"skill_id":{"type":"string","format":"uuid","title":"Skill Id"},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Annotation"},"created":{"type":"string","title":"Created"}},"type":"object","required":["id","skill_id","annotation","created"],"title":"SkillRevisionListItem"},"SkillRevisionSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Annotation"},"created":{"type":"string","title":"Created"}},"type":"object","required":["id","annotation","created"],"title":"SkillRevisionSummary"},"SkillSourceRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["id","name","description","url"],"title":"SkillSourceRead"},"SlackChannelMappingCreate":{"properties":{"channel_id":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"title":"Channel Id","description":"Slack channel ID. If omitted, resolved from channel_name."},"channel_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Channel Name","description":"Human-readable Slack channel name. Used to resolve channel_id when not provided."},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id","description":"TaskAgent assigned to this channel."}},"type":"object","required":["task_agent_id"],"title":"SlackChannelMappingCreate"},"SlackChannelMappingResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Slack channel mapping ID."},"slack_installation_id":{"type":"string","format":"uuid","title":"Slack Installation Id","description":"Parent Slack installation ID."},"channel_id":{"type":"string","title":"Channel Id","description":"Slack channel ID."},"channel_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Channel Name","description":"Human-readable Slack channel name."},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id","description":"TaskAgent assigned to this channel."},"created":{"type":"string","title":"Created","description":"When the channel mapping was created."},"modified":{"type":"string","title":"Modified","description":"When the channel mapping was last updated."}},"type":"object","required":["id","slack_installation_id","channel_id","task_agent_id","created","modified"],"title":"SlackChannelMappingResponse"},"SlackChannelMappingUpdate":{"properties":{"channel_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Channel Name","description":"Human-readable Slack channel name."},"task_agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Id","description":"TaskAgent assigned to this channel."}},"type":"object","title":"SlackChannelMappingUpdate"},"SlackChannelResponse":{"properties":{"id":{"type":"string","title":"Id","description":"Slack channel ID."},"name":{"type":"string","title":"Name","description":"Slack channel name."},"is_private":{"type":"boolean","title":"Is Private","description":"Whether this is a private channel."},"is_archived":{"type":"boolean","title":"Is Archived","description":"Whether this channel is archived."},"is_member":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Member","description":"Whether the installed bot is a member of this channel, when reported by Slack."}},"type":"object","required":["id","name","is_private","is_archived"],"title":"SlackChannelResponse"},"SlackDeleteResponse":{"properties":{"ok":{"type":"boolean","title":"Ok","description":"Whether the delete operation succeeded."}},"type":"object","required":["ok"],"title":"SlackDeleteResponse"},"SlackInstallationResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Slack installation ID."},"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"Project that owns the Slack installation."},"team_id":{"type":"string","title":"Team Id","description":"Slack workspace team ID."},"team_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Team Name","description":"Human-readable Slack workspace name."},"bot_user_id":{"type":"string","title":"Bot User Id","description":"Slack bot user ID for the installed app."},"installed_by_user_id":{"type":"string","format":"uuid","title":"Installed By User Id","description":"User who completed the Slack installation flow."},"status":{"$ref":"#/components/schemas/SlackInstallationStatus","description":"Lifecycle status for the Slack installation."},"default_task_agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Default Task Agent Id","description":"Default TaskAgent used when a channel has no explicit mapping."},"created":{"type":"string","title":"Created","description":"When the installation was created."},"modified":{"type":"string","title":"Modified","description":"When the installation was last updated."}},"type":"object","required":["id","project_id","team_id","bot_user_id","installed_by_user_id","status","created","modified"],"title":"SlackInstallationResponse"},"SlackInstallationStatus":{"type":"string","enum":["active","revoked"],"title":"SlackInstallationStatus"},"SlackInstallationUpdate":{"properties":{"status":{"anyOf":[{"$ref":"#/components/schemas/SlackInstallationStatus"},{"type":"null"}],"description":"Lifecycle status for the Slack installation."},"default_task_agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Default Task Agent Id","description":"Default TaskAgent used when a channel has no explicit mapping."}},"type":"object","title":"SlackInstallationUpdate"},"SlackOAuthStartResponse":{"properties":{"authorize_url":{"type":"string","minLength":1,"format":"uri","title":"Authorize Url","description":"Slack OAuth URL for connecting a workspace."}},"type":"object","required":["authorize_url"],"title":"SlackOAuthStartResponse"},"SourceRow":{"properties":{"source":{"$ref":"#/components/schemas/DocumentSource"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["source","count"],"title":"SourceRow"},"StripePlan":{"type":"string","enum":["trial","pro","teams","enterprise"],"title":"StripePlan"},"Tag":{"properties":{"name":{"type":"string","title":"Name","description":"Alphanumeric name for the tag (max 15 characters). Used to organize and filter Tasks and Task Revisions.","examples":["production","staging","experimental"]},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Optional description for the tag.","examples":["Production environment resources"]},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id","description":"Optional UUID of a parent tag. Used to create hierarchical tag structures (e.g., staging under production).","examples":["01909843-3596-da54-4756-28af46917e74","01909843-3596-da54-4756-28af46917e75"]},"entity_type":{"type":"string","enum":["task","task_revision","task_share","skill","task_agent_revision","task_agent_share"],"title":"Entity Type","description":"The type of entity this tag applies to (task, task_revision, task_share, skill, task_agent_revision, or task_agent_share)","examples":["task","task_revision","task_share","skill","task_agent_revision","task_agent_share"]},"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the tag."},"project_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Project Id","description":"Project this tag belongs to. Null means the tag is global."},"created_at":{"type":"string","title":"Created At","description":"ISO 8601 timestamp when the tag was created."},"children":{"items":{"$ref":"#/components/schemas/Tag"},"type":"array","title":"Children","description":"List of child tags if this tag is used as a parent in a hierarchical structure.","default":[]},"is_project_tag":{"type":"boolean","title":"Is Project Tag","description":"When true, indicates this is a project-level tag that can be used across multiple entity types."},"is_global_tag":{"type":"boolean","title":"Is Global Tag","description":"When true, indicates this is a global tag that is not scoped to a project."},"tagged_entities":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Tagged Entities","description":"List of entity IDs this tag is associated with.","default":[]}},"type":"object","required":["name","entity_type","id","created_at","is_project_tag","is_global_tag"],"title":"Tag","example":{"children":[],"created_at":"2024-01-29T12:34:56.789Z","description":"Production environment resources","id":"123e4567-e89b-12d3-a456-426614174000","is_global_tag":false,"is_project_tag":true,"name":"production","parent_id":"01909843-3596-da54-4756-28af46917e74","project_id":"123e4567-e89b-12d3-a456-426614174001"}},"TagCreate":{"properties":{"name":{"type":"string","title":"Name","description":"Alphanumeric name for the tag (max 15 characters). Used to organize and filter Tasks and Task Revisions.","examples":["production","staging","experimental"]},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Optional description for the tag.","examples":["Production environment resources"]},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id","description":"Optional UUID of a parent tag. Used to create hierarchical tag structures (e.g., staging under production).","examples":["01909843-3596-da54-4756-28af46917e74","01909843-3596-da54-4756-28af46917e75"]}},"type":"object","required":["name"],"title":"TagCreate","example":{"description":"Staging environment resources","name":"staging","parent_id":"01909843-3596-da54-4756-28af46917e74"}},"TagEntityAdd":{"properties":{"entities":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Entities","description":"List of entity IDs affected by this Tag operation","examples":["01909843-3596-da54-4756-28af46917e74","01909843-3596-da54-4756-28af46917e75"]}},"type":"object","required":["entities"],"title":"TagEntityAdd"},"TagEntityRemove":{"properties":{"entities":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Entities","description":"List of entity IDs affected by this Tag operation","examples":["01909843-3596-da54-4756-28af46917e74","01909843-3596-da54-4756-28af46917e75"]}},"type":"object","required":["entities"],"title":"TagEntityRemove"},"TagOutputFormat-Input":{"properties":{"type":{"type":"string","enum":["str","string","boolean","bool","int","integer","list","object","number"],"title":"Type","description":"The desired output type from the LLM."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"A description of the desired content."},"nested_structure":{"anyOf":[{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/TagOutputFormat-Input"},{"type":"string","enum":["str","string","boolean","bool","int","integer","list","object","number"]}]},"type":"object"},{"type":"null"}],"title":"Nested Structure","description":"For lists optionally define the list structure."},"options":{"anyOf":[{"items":{"type":"string"},"type":"array","uniqueItems":true},{"type":"null"}],"title":"Options","description":"Options to constrain the response to a specific set of values."},"item_type":{"anyOf":[{"type":"string","enum":["str","string","boolean","bool","int","integer","list","object","number"]},{"type":"null"}],"title":"Item Type","description":"For lists, the type of items within the list."}},"type":"object","required":["type"],"title":"TagOutputFormat"},"TagOutputFormat-Output":{"additionalProperties":true,"type":"object"},"TagUpdate":{"properties":{"name":{"anyOf":[{"type":"string","description":"Alphanumeric name for the tag (max 15 characters). Used to organize and filter Tasks and Task Revisions.","examples":["production","staging","experimental"]},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description","description":"Optional description for the tag.","examples":["Updated environment resources"]},"parent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Parent Id","description":"Optional UUID of a parent tag. Used to create hierarchical tag structures (e.g., staging under production).","examples":["01909843-3596-da54-4756-28af46917e74","01909843-3596-da54-4756-28af46917e75"]}},"type":"object","title":"TagUpdate","example":{"description":"Beta environment resources","name":"beta"}},"Task":{"properties":{"name":{"type":"string","pattern":"^[a-zA-Z0-9\\- ]+$","title":"Name","description":"A name or reference for the Task."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"A longer description of the Task for internal reference."},"enabled":{"type":"boolean","title":"Enabled","description":"When `true` the Task is active and callable. `false` denotes the Task is not yet operational."},"public":{"type":"boolean","title":"Public","description":"When `true` the Task is public and can be accessed by any User.","default":false},"exposed_to_agents":{"type":"boolean","title":"Exposed To Agents","description":"When `true` the Task is accessible to agents through the unauthenticated agent endpoint.","default":false},"output_modality":{"$ref":"#/components/schemas/OutputModality","description":"Specifies the output modality of the task. Can be 'json', 'image', 'audio', 'pdf', 'text', or 'csv'. Defaults to 'json'.","default":"json"},"task_run_visibility":{"type":"string","enum":["owner_only","editors_and_owners","all_viewers"],"title":"Task Run Visibility","description":"Controls who can view all task runs. 'owner_only' - only task owners see all runs (default), 'editors_and_owners' - task editors and owners see all runs, 'all_viewers' - all users with view permission see all runs.","default":"owner_only"},"id":{"type":"string","format":"uuid","title":"Id","description":"The unique identifier of the Task."},"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"The Project that the Task belongs to."},"created":{"type":"string","title":"Created","description":"When the Task was created."},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified","description":"When the Task was last updated."},"deleted":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Deleted","description":"Timestamp when the task was deleted, if applicable."},"revisions":{"items":{"$ref":"#/components/schemas/TaskRevision"},"type":"array","title":"Revisions","description":"Each update to a Task results in a new Revision being created. Task Revisions are a powerful concept that can be used to assist with A/B testing, comparing responses from different LLM's, etc.","default":[]},"access_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Access Token","description":"Task specific Bearer token that can be used to authenticated when executing this Task."},"active_revisions":{"items":{"$ref":"#/components/schemas/TaskActiveRevision"},"type":"array","title":"Active Revisions","description":"The revision currently active for this Task."},"cloned_from_task_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Cloned From Task Revision Id","description":"The unique identifier of the task revision this task was cloned from, if applicable.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"tags":{"items":{"$ref":"#/components/schemas/Tag"},"type":"array","title":"Tags","default":[]},"shared_with_project":{"type":"boolean","title":"Shared With Project","description":"When `true` the Task is shared with members of its Project.","default":false}},"type":"object","required":["name","enabled","id","project_id","created","access_token","active_revisions"],"title":"Task","example":{"access_token":"TASK_ACCESS_TOKEN_REDACTED","active_revisions":[{"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","weight":1.0}],"created":"2024-06-13T14:01:03.021673","description":"A task to pre-triage user onboarding before IDV.","enabled":true,"exposed_to_agents":false,"id":"019011e6-e530-3aca-6cf7-2973387c255d","modified":"2024-06-13T14:01:03.021673","name":"Fintech Pre-Triage","project_id":"019010a2-8327-2607-11d7-41bb0a8936d4","public":false,"revisions":[{"active":true,"annotation":"Production v2 - Added image matching capability","created":"2024-06-13T14:01:03.021673","file_input_mode":"image","id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","input_processors":[{"config":{"extract_text":true,"include_title":true,"max_length":5000},"input_processor":"url_fetcher","param_name":"description"}],"llm_config":{"temperature":0.7},"llm_model":{"alias":"GPT-4 Turbo","created":"2024-01-16T13:33:25.247662","description":"Latest GPT-4 model with 128k context window and knowledge cutoff of December 2023.","id":"019011e6-e530-3aca-6cf7-2973387c255d","modified":"2024-01-16T13:33:25.247662","name":"gpt-4-turbo-preview","provider":"OpenAI","supports_vision":true,"vendor":"openai"},"llm_model_id":"019011e6-e530-3aca-6cf7-2973387c255d","modified":"2024-06-13T14:01:03.021673","optimise_images":true,"output_format":{"compliance":"bool","hint":{"type":"str"},"match":{"description":"True if the provided description is a close match","type":"bool"},"rationale":"str"},"rag":{"collection_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","rag_config":{"candidate_k":12,"final_k":5,"include_sources":true,"max_context_chunks":5,"max_context_tokens":4000,"rewrite_mode":"single_query"}},"system_prompt":"You are an expert software program specifically designed for the fintech industry that will be used for pre-triage tasks to ensure the best possible client UX and efficient 3rd party platform interoperability.","tags":[],"task_forwarder_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","test":false,"user_prompt":"Your task is to validate the uploaded image and determine whether it will be suitable for authentication and onboarding checks. If the image of the person is clear and typical of a passport style photo then set the compliance field to true. Provide rationale for your decision in the rationale field. If the compliance result is false, then provide a helpful hint for the customer who has submitted the photo informing them why it is unacceptable and some steps to remedy it, place this into the hint field. Determine whether the following description matches the provided image: {description}"}]}},"TaskActiveRevision":{"properties":{"task_revision_id":{"type":"string","format":"uuid","title":"Task Revision Id","description":"The unique identifier of the Task Revision to activate. Each Task can have multiple revisions, but only active ones will be used for execution.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"weight":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Weight","description":"The traffic weight for this revision (between 0 and 1). When multiple revisions are active, weights determine the proportion of traffic each receives. Must sum to 1.0 across all active revisions.","default":1.0,"examples":[0.5,1.0]}},"type":"object","required":["task_revision_id"],"title":"TaskActiveRevision","example":{"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","weight":1.0}},"TaskAgentApprovalActorType":{"type":"string","enum":["user","trigger","system","anonymous"],"title":"TaskAgentApprovalActorType","description":"Actor source that requested an approval-gated action."},"TaskAgentApprovalDecision":{"type":"string","enum":["approved","rejected"],"title":"TaskAgentApprovalDecision","description":"Human decision values for TaskAgent approval requests."},"TaskAgentApprovalRequestApprove":{"properties":{"decision_note":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Decision Note"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"Optional shorter one-shot allowance expiry for a future resume path."}},"additionalProperties":false,"type":"object","title":"TaskAgentApprovalRequestApprove","description":"Approve a pending TaskAgent approval request."},"TaskAgentApprovalRequestRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"task_agent_revision_id":{"type":"string","format":"uuid","title":"Task Agent Revision Id"},"task_agent_run_id":{"type":"string","format":"uuid","title":"Task Agent Run Id"},"session_id":{"type":"string","title":"Session Id"},"adk_session_user_id":{"type":"string","title":"Adk Session User Id"},"invocation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invocation Id"},"function_call_id":{"type":"string","title":"Function Call Id"},"adk_event_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Adk Event Id"},"requested_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Requested By User Id"},"requested_by_actor_type":{"$ref":"#/components/schemas/TaskAgentApprovalActorType"},"requested_by_actor_ref":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Requested By Actor Ref"},"decided_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Decided By User Id"},"requester_is_decider":{"type":"boolean","title":"Requester Is Decider","default":false},"tool_action_control_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Tool Action Control Id"},"action_mode_snapshot":{"type":"string","title":"Action Mode Snapshot"},"tool_type":{"$ref":"#/components/schemas/TaskAgentToolSource"},"tool_name":{"type":"string","title":"Tool Name"},"tool_ref":{"additionalProperties":true,"type":"object","title":"Tool Ref"},"tool_args_hash":{"type":"string","title":"Tool Args Hash"},"tool_args_preview":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Args Preview"},"agent_reason":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Agent Reason","description":"Optional untrusted model-authored rationale, displayed as Agent reason."},"status":{"$ref":"#/components/schemas/TaskAgentApprovalRequestStatus"},"decision":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentApprovalDecision"},{"type":"null"}]},"decision_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision Note"},"created":{"type":"string","title":"Created"},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"},"decided_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decided At"},"expires_at":{"type":"string","title":"Expires At"}},"type":"object","required":["id","project_id","task_agent_id","task_agent_revision_id","task_agent_run_id","session_id","adk_session_user_id","function_call_id","requested_by_actor_type","action_mode_snapshot","tool_type","tool_name","tool_ref","tool_args_hash","status","created","expires_at"],"title":"TaskAgentApprovalRequestRead","description":"Approval request response for a proposed TaskAgent tool call."},"TaskAgentApprovalRequestReject":{"properties":{"decision_note":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Decision Note"}},"additionalProperties":false,"type":"object","title":"TaskAgentApprovalRequestReject","description":"Reject a pending TaskAgent approval request."},"TaskAgentApprovalRequestResume":{"properties":{"task_agent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Run Id","description":"Optional linked TaskAgentRun ID guard."},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Optional linked ADK session ID guard."},"message":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Message","description":"Optional continuation message. Omit to use the controlled internal approval-resume continuation message."}},"additionalProperties":false,"type":"object","title":"TaskAgentApprovalRequestResume","description":"Resume a paused TaskAgent approval request."},"TaskAgentApprovalRequestStatus":{"type":"string","enum":["pending","approved","rejected","expired","cancelled"],"title":"TaskAgentApprovalRequestStatus","description":"Lifecycle status for TaskAgent tool approval requests."},"TaskAgentChaosConfig":{"properties":{"enabled":{"type":"boolean","title":"Enabled","default":true},"seed":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Seed"},"run_index":{"type":"integer","maximum":100000.0,"minimum":0.0,"title":"Run Index","default":0},"max_faults":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Max Faults","default":1},"modes":{"items":{"oneOf":[{"$ref":"#/components/schemas/TaskAgentChaosToolErrorMode"},{"$ref":"#/components/schemas/TaskAgentChaosToolLatencyMode"},{"$ref":"#/components/schemas/TaskAgentChaosModelErrorMode"}],"discriminator":{"propertyName":"type","mapping":{"model_error":"#/components/schemas/TaskAgentChaosModelErrorMode","tool_error":"#/components/schemas/TaskAgentChaosToolErrorMode","tool_latency":"#/components/schemas/TaskAgentChaosToolLatencyMode"}}},"type":"array","maxItems":10,"title":"Modes"}},"additionalProperties":false,"type":"object","title":"TaskAgentChaosConfig","description":"Run-scoped TaskAgent chaos policy."},"TaskAgentChaosEventRead":{"properties":{"event_id":{"type":"string","title":"Event Id"},"type":{"type":"string","title":"Type"},"applied":{"type":"boolean","title":"Applied"},"seed":{"type":"string","title":"Seed"},"sample":{"type":"number","title":"Sample"},"threshold":{"type":"number","title":"Threshold"},"decision_key":{"type":"string","title":"Decision Key"},"call_index":{"type":"integer","title":"Call Index"},"target":{"additionalProperties":true,"type":"object","title":"Target"},"phase":{"type":"string","title":"Phase"},"occurred_at":{"type":"string","title":"Occurred At"},"call_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Call Id"},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Latency Ms"},"tool_execution_skipped":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Tool Execution Skipped"},"retryable":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Retryable"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"variant":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"}},"additionalProperties":true,"type":"object","required":["event_id","type","applied","seed","sample","threshold","decision_key","call_index","target","phase","occurred_at"],"title":"TaskAgentChaosEventRead","description":"Redacted chaos event persisted on a TaskAgentRun."},"TaskAgentChaosLatencyRange":{"properties":{"min":{"type":"integer","maximum":5000.0,"minimum":0.0,"title":"Min"},"max":{"type":"integer","maximum":5000.0,"minimum":0.0,"title":"Max"}},"additionalProperties":false,"type":"object","required":["min","max"],"title":"TaskAgentChaosLatencyRange","description":"Bounded per-fault latency injection range."},"TaskAgentChaosModelErrorMode":{"properties":{"probability":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Probability"},"type":{"type":"string","const":"model_error","title":"Type"},"error":{"type":"string","enum":["timeout","rate_limit","provider_unavailable","transient_internal"],"title":"Error"}},"additionalProperties":false,"type":"object","required":["probability","type","error"],"title":"TaskAgentChaosModelErrorMode","description":"Synthetic primary model failure mode."},"TaskAgentChaosTargets":{"properties":{"tool_names":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Tool Names"},"sources":{"anyOf":[{"items":{"type":"string","enum":["task","mcp","integration","registered_tool"]},"type":"array"},{"type":"null"}],"title":"Sources"}},"additionalProperties":false,"type":"object","title":"TaskAgentChaosTargets","description":"Tool targets eligible for a chaos mode."},"TaskAgentChaosToolErrorMode":{"properties":{"probability":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Probability"},"type":{"type":"string","const":"tool_error","title":"Type"},"retryable":{"type":"boolean","title":"Retryable","default":false},"targets":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentChaosTargets"},{"type":"null"}]},"variant":{"anyOf":[{"type":"string","enum":["empty_result","missing_fields","null_fields","unexpected_nesting","truncated_result","stale_result"]},{"type":"null"}],"title":"Variant"}},"additionalProperties":false,"type":"object","required":["probability","type"],"title":"TaskAgentChaosToolErrorMode","description":"Synthetic tool failure or malformed response mode."},"TaskAgentChaosToolLatencyMode":{"properties":{"probability":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Probability"},"type":{"type":"string","const":"tool_latency","title":"Type"},"targets":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentChaosTargets"},{"type":"null"}]},"latency_ms":{"$ref":"#/components/schemas/TaskAgentChaosLatencyRange"}},"additionalProperties":false,"type":"object","required":["probability","type","latency_ms"],"title":"TaskAgentChaosToolLatencyMode","description":"Bounded tool latency mode."},"TaskAgentCloneDependencyReportItem":{"properties":{"kind":{"type":"string","enum":["task","task_revision","skill","skill_revision","integration","integration_tool","mcp_server","mcp_tool","registered_tool","llm_model"],"title":"Kind"},"source_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Id"},"target_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Target Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"action":{"type":"string","enum":["cloned","reused","created_placeholder","preserved","skipped","failed"],"title":"Action"},"status":{"type":"string","enum":["ready","setup_required","warning","failed"],"title":"Status"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"type":"object","required":["kind","action","status"],"title":"TaskAgentCloneDependencyReportItem","description":"Dependency action produced while cloning a shared TaskAgent."},"TaskAgentCloneResult":{"properties":{"task_agent":{"$ref":"#/components/schemas/TaskAgentRead"},"runnable":{"type":"boolean","title":"Runnable"},"dependency_report":{"items":{"$ref":"#/components/schemas/TaskAgentCloneDependencyReportItem"},"type":"array","title":"Dependency Report"}},"type":"object","required":["task_agent","runnable"],"title":"TaskAgentCloneResult","description":"Result wrapper for authenticated TaskAgent share clone."},"TaskAgentContextUsageCache":{"properties":{"enabled":{"type":"boolean","title":"Enabled","default":false},"gross_input_tokens":{"type":"integer","minimum":0.0,"title":"Gross Input Tokens","default":0},"cached_input_tokens":{"type":"integer","minimum":0.0,"title":"Cached Input Tokens","default":0},"cached_input_billing_ratio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cached Input Billing Ratio"},"billing_input_tokens":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Billing Input Tokens"},"billing_cached_read_input_tokens":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Billing Cached Read Input Tokens"},"requests_with_cached_tokens":{"type":"integer","minimum":0.0,"title":"Requests With Cached Tokens","default":0}},"type":"object","title":"TaskAgentContextUsageCache"},"TaskAgentContextUsageInputFiles":{"properties":{"estimated_tokens":{"type":"integer","minimum":0.0,"title":"Estimated Tokens","default":0},"file_count":{"type":"integer","minimum":0.0,"title":"File Count","default":0},"text_file_count":{"type":"integer","minimum":0.0,"title":"Text File Count","default":0},"binary_file_count":{"type":"integer","minimum":0.0,"title":"Binary File Count","default":0},"total_bytes":{"type":"integer","minimum":0.0,"title":"Total Bytes","default":0}},"type":"object","title":"TaskAgentContextUsageInputFiles"},"TaskAgentContextUsageInputTokens":{"properties":{"provider_total":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Provider Total"},"observed_provider_total":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Observed Provider Total"},"estimated_total":{"type":"integer","minimum":0.0,"title":"Estimated Total","default":0},"uncategorized":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Uncategorized"},"breakdown":{"additionalProperties":{"type":"integer"},"type":"object","title":"Breakdown"}},"type":"object","title":"TaskAgentContextUsageInputTokens"},"TaskAgentContextUsageMetadata":{"properties":{"request_count":{"type":"integer","minimum":0.0,"title":"Request Count","default":0},"partial":{"type":"boolean","title":"Partial","default":false},"provider_usage_missing":{"type":"boolean","title":"Provider Usage Missing","default":false},"provider_usage_complete":{"type":"boolean","title":"Provider Usage Complete","default":false},"observed_provider_total_tokens":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Observed Provider Total Tokens"},"context_window_attempted_input_tokens":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Context Window Attempted Input Tokens"},"context_window_limit_tokens":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Context Window Limit Tokens"},"estimation_truncated":{"type":"boolean","title":"Estimation Truncated","default":false},"truncated_estimate_count":{"type":"integer","minimum":0.0,"title":"Truncated Estimate Count","default":0},"max_estimated_part_bytes":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Max Estimated Part Bytes"},"estimation_methods":{"items":{"type":"string"},"type":"array","title":"Estimation Methods"}},"type":"object","title":"TaskAgentContextUsageMetadata"},"TaskAgentContextUsageOutputTokens":{"properties":{"provider_total":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Provider Total"},"observed_provider_total":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Observed Provider Total"}},"type":"object","title":"TaskAgentContextUsageOutputTokens"},"TaskAgentContextUsageRead":{"properties":{"schema_version":{"type":"integer","title":"Schema Version","default":1},"estimator_version":{"type":"string","title":"Estimator Version"},"input_tokens":{"$ref":"#/components/schemas/TaskAgentContextUsageInputTokens"},"input_files":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentContextUsageInputFiles"},{"type":"null"}]},"output_tokens":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentContextUsageOutputTokens"},{"type":"null"}]},"cache":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentContextUsageCache"},{"type":"null"}]},"runtime_components":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentRuntimeComponentContextUsage"},"type":"object","title":"Runtime Components"},"metadata":{"$ref":"#/components/schemas/TaskAgentContextUsageMetadata"}},"type":"object","required":["estimator_version","input_tokens"],"title":"TaskAgentContextUsageRead"},"TaskAgentCreate":{"properties":{"name":{"type":"string","maxLength":255,"title":"Name","description":"Name of the TaskAgent.","examples":["Research Assistant"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Description of the TaskAgent.","examples":["An agent that can summarize and translate documents."]},"instruction":{"type":"string","title":"Instruction","description":"System prompt / instruction for the agent.","examples":["You are a helpful assistant that can summarize and translate text."]},"mode":{"$ref":"#/components/schemas/TaskAgentMode","description":"Execution mode for the agent.","default":"agentic","examples":["agentic"]},"llm_model_id":{"type":"string","format":"uuid","title":"Llm Model Id","description":"ID of the LLM model to use.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"fallback_llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Fallback Llm Model Id","description":"Optional fallback LLM model to snapshot for future failover support.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f9"]},"task_tools":{"items":{"$ref":"#/components/schemas/TaskAgentTaskToolInput"},"type":"array","title":"Task Tools","description":"Task tools to add. Order in array determines execution order (index 0 = order 0).","default":[],"examples":[[{"task_id":"0190a234-8dc6-6d08-aea9-928fcecad8f2"}]]},"mcp_servers":{"items":{"$ref":"#/components/schemas/TaskAgentMcpServerInput"},"type":"array","title":"Mcp Servers","description":"MCP servers to attach. Use allowed_tool_ids for tool restriction.","default":[]},"integrations":{"items":{"$ref":"#/components/schemas/TaskAgentIntegrationInput"},"type":"array","title":"Integrations","description":"Platform integrations to attach. Use allowed_tool_ids for tool restriction.","default":[]},"skills":{"items":{"$ref":"#/components/schemas/TaskAgentSkillInput"},"type":"array","title":"Skills","description":"Declarative skills to attach. Order in array determines activation precedence.","default":[]},"memory_strategy":{"anyOf":[{"type":"string","enum":["sliding_window","compaction"]},{"type":"null"}],"title":"Memory Strategy","description":"Memory management strategy. None = unlimited history."},"memory_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Memory Config","description":"Strategy-specific configuration. Required when memory_strategy is set."},"max_turns":{"anyOf":[{"type":"integer","maximum":500.0,"minimum":1.0},{"type":"null"}],"title":"Max Turns","description":"Max conversation turns per session. None = unlimited."},"task_agent_run_visibility":{"type":"string","enum":["owner_only","editors_and_owners","all_viewers"],"title":"Task Agent Run Visibility","description":"Controls who can see all TaskAgent runs for this agent.","default":"owner_only"}},"additionalProperties":false,"type":"object","required":["name","instruction","llm_model_id"],"title":"TaskAgentCreate","description":"Schema for creating a TaskAgent.\n\n``registered_tools`` are intentionally omitted from the public write\ncontract. They remain skill-managed and internal-only."},"TaskAgentCreditReport":{"properties":{"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id","description":"Unique identifier of the TaskAgent.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"date_range":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object","title":"Date Range","description":"Time period covered by the report.","examples":[{"end":"2024-01-31T23:59:59Z","start":"2024-01-01T00:00:00Z"}]},"total_credits":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Credits","description":"Total credits charged across TaskAgent runs in the reporting period.","examples":["350.00"]},"total_runs":{"type":"integer","minimum":0.0,"title":"Total Runs","description":"Number of TaskAgent runs included in the report.","examples":[150]}},"type":"object","required":["task_agent_id","date_range","total_credits","total_runs"],"title":"TaskAgentCreditReport","description":"Aggregate credit usage for a TaskAgent."},"TaskAgentEvalJudgeConfig":{"properties":{"objective":{"type":"string","maxLength":2000,"minLength":1,"title":"Objective"},"rubric":{"items":{"type":"string","maxLength":1000,"minLength":1},"type":"array","maxItems":20,"minItems":1,"title":"Rubric"}},"additionalProperties":false,"type":"object","required":["objective","rubric"],"title":"TaskAgentEvalJudgeConfig"},"TaskAgentEvalJudgeModelResponse":{"properties":{"name":{"type":"string","title":"Name"},"provider":{"type":"string","title":"Provider"}},"type":"object","required":["name","provider"],"title":"TaskAgentEvalJudgeModelResponse"},"TaskAgentEvalMetricComparison":{"properties":{"reference_avg":{"type":"number","title":"Reference Avg"},"candidate_avg":{"type":"number","title":"Candidate Avg"},"delta_pct":{"type":"number","title":"Delta Pct"}},"type":"object","required":["reference_avg","candidate_avg","delta_pct"],"title":"TaskAgentEvalMetricComparison"},"TaskAgentEvalResultMetrics":{"properties":{"reference":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalResultRunMetrics"},{"type":"null"}]},"candidate":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalResultRunMetrics"},{"type":"null"}]}},"type":"object","title":"TaskAgentEvalResultMetrics"},"TaskAgentEvalResultResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"eval_run_id":{"type":"string","format":"uuid","title":"Eval Run Id"},"eval_case_id":{"type":"string","format":"uuid","title":"Eval Case Id"},"reference_run_id":{"type":"string","format":"uuid","title":"Reference Run Id"},"candidate_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Candidate Run Id"},"verdict":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalVerdict"},{"type":"null"}]},"reasoning":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reasoning"},"judge_input_tokens":{"type":"integer","title":"Judge Input Tokens"},"judge_output_tokens":{"type":"integer","title":"Judge Output Tokens"},"is_error":{"type":"boolean","title":"Is Error"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"created":{"type":"string","title":"Created"},"metrics":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalResultMetrics"},{"type":"null"}]}},"type":"object","required":["id","eval_run_id","eval_case_id","reference_run_id","judge_input_tokens","judge_output_tokens","is_error","created"],"title":"TaskAgentEvalResultResponse"},"TaskAgentEvalResultRunMetrics":{"properties":{"total_tokens":{"type":"integer","title":"Total Tokens"},"charged_credits":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Charged Credits"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms"}},"type":"object","required":["total_tokens","charged_credits","duration_ms"],"title":"TaskAgentEvalResultRunMetrics"},"TaskAgentEvalRunCreate":{"properties":{"candidate_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Candidate Revision Id"},"eval_set_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Eval Set Id"},"task_agent_run_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":20,"minItems":1},{"type":"null"}],"title":"Task Agent Run Ids"},"last_n":{"anyOf":[{"type":"integer","maximum":20.0,"minimum":1.0},{"type":"null"}],"title":"Last N"},"judge_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Judge Model Id"},"judge_config":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalJudgeConfig"},{"type":"null"}]}},"type":"object","title":"TaskAgentEvalRunCreate"},"TaskAgentEvalRunDetailResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"candidate_revision_id":{"type":"string","format":"uuid","title":"Candidate Revision Id"},"eval_set_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Eval Set Id"},"status":{"$ref":"#/components/schemas/TaskAgentEvalStatus"},"pass_count":{"type":"integer","title":"Pass Count"},"fail_count":{"type":"integer","title":"Fail Count"},"error_count":{"type":"integer","title":"Error Count"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"last_activity_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Activity At"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"created_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By User Id"},"judge_model":{"$ref":"#/components/schemas/TaskAgentEvalJudgeModelResponse"},"judge_config":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalJudgeConfig"},{"type":"null"}]},"metrics":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalRunMetrics"},{"type":"null"}]},"results":{"items":{"$ref":"#/components/schemas/TaskAgentEvalResultResponse"},"type":"array","title":"Results"},"task_agent_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Agent Run Ids","readOnly":true},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","readOnly":true}},"type":"object","required":["id","task_agent_id","project_id","candidate_revision_id","status","pass_count","fail_count","error_count","created","modified","judge_model","task_agent_run_ids","pass_rate"],"title":"TaskAgentEvalRunDetailResponse"},"TaskAgentEvalRunMetrics":{"properties":{"token_cost":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalMetricComparison"},{"type":"null"}]},"charged_credits":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalMetricComparison"},{"type":"null"}]},"duration_ms":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentEvalMetricComparison"},{"type":"null"}]}},"type":"object","title":"TaskAgentEvalRunMetrics"},"TaskAgentEvalRunResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"candidate_revision_id":{"type":"string","format":"uuid","title":"Candidate Revision Id"},"eval_set_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Eval Set Id"},"status":{"$ref":"#/components/schemas/TaskAgentEvalStatus"},"pass_count":{"type":"integer","title":"Pass Count"},"fail_count":{"type":"integer","title":"Fail Count"},"error_count":{"type":"integer","title":"Error Count"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"last_activity_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Activity At"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"created_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By User Id"},"task_agent_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Agent Run Ids","readOnly":true},"pass_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Pass Rate","readOnly":true}},"type":"object","required":["id","task_agent_id","project_id","candidate_revision_id","status","pass_count","fail_count","error_count","created","modified","task_agent_run_ids","pass_rate"],"title":"TaskAgentEvalRunResponse"},"TaskAgentEvalSetCreate":{"properties":{"name":{"type":"string","maxLength":64,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Description"},"task_agent_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":20,"minItems":1,"title":"Task Agent Run Ids"}},"type":"object","required":["name","task_agent_run_ids"],"title":"TaskAgentEvalSetCreate"},"TaskAgentEvalSetResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"created_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By User Id"},"task_agent_run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Agent Run Ids","readOnly":true}},"type":"object","required":["id","name","task_agent_id","project_id","created","modified","task_agent_run_ids"],"title":"TaskAgentEvalSetResponse"},"TaskAgentEvalSetUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Description"},"task_agent_run_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array","maxItems":20,"minItems":1},{"type":"null"}],"title":"Task Agent Run Ids"}},"type":"object","title":"TaskAgentEvalSetUpdate"},"TaskAgentEvalStatus":{"type":"string","enum":["pending","running","completed","failed"],"title":"TaskAgentEvalStatus","description":"Status of a TaskAgent eval run."},"TaskAgentEvalVerdict":{"type":"string","enum":["pass","fail"],"title":"TaskAgentEvalVerdict","description":"Judge verdict for a TaskAgent eval result."},"TaskAgentEvent":{"properties":{"id":{"type":"string","title":"Id","description":"Event ID from ADK session."},"author":{"type":"string","title":"Author","description":"Event author: 'user' or agent name.","examples":["user"]},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Text content of the event (extracted from parts)."},"timestamp":{"type":"string","format":"date-time","title":"Timestamp","description":"When the event occurred."},"event_type":{"type":"string","title":"Event Type","description":"Type of event.","examples":["user_message","agent_response","tool_call","tool_result","formatted_output","memory_compaction","error"]},"tool_calls":{"anyOf":[{"items":{"$ref":"#/components/schemas/ToolCallInfo"},"type":"array"},{"type":"null"}],"title":"Tool Calls","description":"Tool calls made in this event. Multiple if parallel calls."},"tool_results":{"anyOf":[{"items":{"$ref":"#/components/schemas/ToolResultInfo"},"type":"array"},{"type":"null"}],"title":"Tool Results","description":"Tool results in this event. Multiple if parallel results."},"files":{"items":{"$ref":"#/components/schemas/TaskAgentFileMetadata"},"type":"array","title":"Files","description":"Files uploaded with this user message. Populated only for user_message events."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error message if event_type is error."},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Event-specific metadata for system events such as memory compaction."}},"type":"object","required":["id","author","timestamp","event_type"],"title":"TaskAgentEvent","description":"Event from a TaskAgent conversation (from ADK session).\n\nNote: ADK may store multiple parallel tool calls or results in a single event.\nUse tool_calls/tool_results lists to access all of them."},"TaskAgentFileMetadata":{"properties":{"original_filename":{"type":"string","title":"Original Filename","description":"The original filename as submitted by the user","examples":["contract.pdf","photo.jpg"]},"stored_filename":{"type":"string","title":"Stored Filename","description":"The generated filename used for storage","examples":["b4a66744-6e99-4ad4-8aff-4d953bb0b9cf.pdf"]},"content_type":{"type":"string","title":"Content Type","description":"MIME type of the file","examples":["application/pdf","image/jpeg"]},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url","description":"Relative URL to download the file (generated dynamically, not stored in database)","examples":["/org/abc123.../project/def456.../task/ghi789.../run/jkl012.../file/b4a66744-6e99-4ad4-8aff-4d953bb0b9cf.pdf"]},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size Bytes","description":"File size in bytes (if available)","examples":[1024576]},"source":{"type":"string","enum":["input","generated"],"title":"Source","description":"Source of the file: 'input' for uploaded files, 'generated' for task tool outputs","default":"input"},"source_task_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Task Name","description":"Name of the task tool/task that generated this file (only for generated files)","examples":["quote-image-generator"]},"source_task_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Task Run Id","description":"TaskRun ID that generated this file (only for generated files)","examples":["019beb35-3976-e7da-4595-56338335cd5a"]}},"type":"object","required":["original_filename","stored_filename","content_type"],"title":"TaskAgentFileMetadata","description":"Extended file metadata for TaskAgent runs with provenance tracking.\n\nInherits from TaskRunFileMetadata and adds fields to track whether\na file was uploaded with the request or generated by a task tool.","example":{"content_type":"application/pdf","download_url":"/org/abc/project/def/task/ghi/run/jkl/file/b4a66744-6e99-4ad4-8aff-4d953bb0b9cf.pdf","original_filename":"my-document.pdf","size_bytes":1024576,"stored_filename":"b4a66744-6e99-4ad4-8aff-4d953bb0b9cf.pdf"}},"TaskAgentIntegrationInput":{"properties":{"project_integration_id":{"type":"string","format":"uuid","title":"Project Integration Id","description":"ID of the ProjectIntegration to attach."},"credential_policy":{"anyOf":[{"type":"string","enum":["invoker","project_default"]},{"type":"null"}],"title":"Credential Policy","description":"Credential selection policy. Omission is allowed only when the provider declares an unambiguous default."},"allowed_tool_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Allowed Tool Ids","description":"Optional IntegrationTool IDs to expose. None uses the integration provider's enabled, default-selected tools."},"default_action_mode":{"$ref":"#/components/schemas/TaskAgentToolActionMode","description":"Default action mode for tools exposed by this integration.","default":"auto_run"},"default_approval_percent":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Default Approval Percent","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory.","default":100},"default_rejection_behavior":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior","description":"Default rejection behavior for approval-gated integration tools.","default":"end_run"},"tool_action_modes":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentToolActionMode"},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Action Modes","description":"Per-tool action mode overrides keyed by IntegrationTool ID."},"tool_approval_percents":{"additionalProperties":{"type":"integer","maximum":100.0,"minimum":1.0,"description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory."},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Approval Percents","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory."},"tool_rejection_behaviors":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior"},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Rejection Behaviors","description":"Per-tool rejection behavior overrides keyed by IntegrationTool ID."}},"type":"object","required":["project_integration_id"],"title":"TaskAgentIntegrationInput"},"TaskAgentIntegrationRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"project_integration_id":{"type":"string","format":"uuid","title":"Project Integration Id"},"integration_type":{"type":"string","enum":["google_sheets","google_docs","google_slides","google_calendar","google_gmail","slack","teams","xero"],"title":"Integration Type"},"integration_name":{"type":"string","title":"Integration Name"},"order":{"type":"integer","title":"Order"},"enabled":{"type":"boolean","title":"Enabled"},"credential_policy":{"$ref":"#/components/schemas/IntegrationCredentialPolicy"},"allowed_tool_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Allowed Tool Ids"},"default_action_mode":{"$ref":"#/components/schemas/TaskAgentToolActionMode","default":"auto_run"},"default_approval_percent":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Default Approval Percent","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory.","default":100},"default_rejection_behavior":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior","default":"end_run"},"tool_action_modes":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentToolActionMode"},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Action Modes"},"tool_approval_percents":{"additionalProperties":{"type":"integer","maximum":100.0,"minimum":1.0,"description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory."},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Approval Percents","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory."},"tool_rejection_behaviors":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior"},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Rejection Behaviors"},"provision_source":{"type":"string","enum":["manual","skill_capability"],"title":"Provision Source"},"source_skill_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Skill Id"},"source_skill_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Skill Revision Id"},"source_capability_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Capability Id"},"tool_count":{"type":"integer","title":"Tool Count","description":"Number of integration tools available to the agent.","readOnly":true}},"type":"object","required":["id","project_integration_id","integration_type","integration_name","order","enabled","credential_policy","provision_source","tool_count"],"title":"TaskAgentIntegrationRead"},"TaskAgentMcpServerInput":{"properties":{"task_mcp_server_id":{"type":"string","format":"uuid","title":"Task Mcp Server Id","description":"ID of the TaskMcpServer to attach."},"allowed_tool_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Allowed Tool Ids","description":"Optional TaskMcpTool IDs to expose. None means all enabled server tools; an empty list means no tools."},"default_action_mode":{"$ref":"#/components/schemas/TaskAgentToolActionMode","description":"Default action mode for tools exposed by this MCP attachment.","default":"auto_run"},"default_approval_percent":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Default Approval Percent","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory.","default":100},"default_rejection_behavior":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior","description":"Default rejection behavior for approval-gated MCP tools.","default":"end_run"},"tool_action_modes":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentToolActionMode"},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Action Modes","description":"Per-tool action mode overrides keyed by TaskMcpTool ID."},"tool_approval_percents":{"additionalProperties":{"type":"integer","maximum":100.0,"minimum":1.0,"description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory."},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Approval Percents","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory."},"tool_rejection_behaviors":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior"},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Rejection Behaviors","description":"Per-tool rejection behavior overrides keyed by TaskMcpTool ID."}},"type":"object","required":["task_mcp_server_id"],"title":"TaskAgentMcpServerInput","description":"MCP server to attach to a TaskAgent."},"TaskAgentMcpServerRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_mcp_server_id":{"type":"string","format":"uuid","title":"Task Mcp Server Id"},"task_mcp_server_name":{"type":"string","title":"Task Mcp Server Name","description":"Name of the MCP server."},"order":{"type":"integer","title":"Order","description":"Execution order (0-indexed)."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether this MCP server is enabled."},"allowed_tool_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Allowed Tool Ids","description":"Restricted tool IDs. None means all enabled tools; an empty list means no tools."},"default_action_mode":{"$ref":"#/components/schemas/TaskAgentToolActionMode","default":"auto_run"},"default_approval_percent":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Default Approval Percent","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory.","default":100},"default_rejection_behavior":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior","default":"end_run"},"tool_action_modes":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentToolActionMode"},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Action Modes"},"tool_approval_percents":{"additionalProperties":{"type":"integer","maximum":100.0,"minimum":1.0,"description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory."},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Approval Percents","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory."},"tool_rejection_behaviors":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior"},"propertyNames":{"format":"uuid"},"type":"object","title":"Tool Rejection Behaviors"},"provision_source":{"type":"string","enum":["manual","skill_capability"],"title":"Provision Source"},"source_skill_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Skill Id"},"source_skill_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Skill Revision Id"},"source_capability_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Capability Id"},"tool_count":{"type":"integer","title":"Tool Count","description":"Number of tools available to the agent.","readOnly":true}},"type":"object","required":["id","task_mcp_server_id","task_mcp_server_name","order","enabled","provision_source","tool_count"],"title":"TaskAgentMcpServerRead","description":"MCP server association in a TaskAgent read response."},"TaskAgentMode":{"type":"string","enum":["agentic","sequential"],"title":"TaskAgentMode","description":"Execution mode for TaskAgent."},"TaskAgentRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"name":{"type":"string","title":"Name"},"active_revision":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentRevisionSummary"},{"type":"null"}]},"revisions":{"items":{"$ref":"#/components/schemas/TaskAgentRevisionRead"},"type":"array","title":"Revisions"},"task_agent_run_visibility":{"type":"string","enum":["owner_only","editors_and_owners","all_viewers"],"title":"Task Agent Run Visibility"},"shared_with_project":{"type":"boolean","title":"Shared With Project","description":"When `true` the TaskAgent is shared with members of its Project.","default":false},"seven_day_summary":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentSevenDaySummary"},{"type":"null"}],"description":"Optional summary of visible TaskAgent runs created in the last seven days. Populated when the list endpoint is called with `seven_day_summary=true`."},"is_deleted":{"type":"boolean","title":"Is Deleted"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"type":"object","required":["id","name","task_agent_run_visibility","is_deleted","created","modified"],"title":"TaskAgentRead","description":"Schema for reading a TaskAgent."},"TaskAgentRegisteredToolRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"registered_tool_key":{"type":"string","title":"Registered Tool Key"},"registered_tool_version":{"type":"string","title":"Registered Tool Version","description":"Pinned immutable runtime implementation version."},"order":{"type":"integer","title":"Order","description":"Attachment order (0-indexed)."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether this registered tool is enabled."},"provision_source":{"type":"string","enum":["manual","skill_capability"],"title":"Provision Source"},"source_skill_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Skill Id"},"source_skill_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Source Skill Revision Id"},"source_capability_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Capability Id"},"name":{"type":"string","title":"Name","description":"Human-readable name of the registered first-party tool.","readOnly":true},"tool_names":{"items":{"type":"string"},"type":"array","title":"Tool Names","description":"Concrete tool names reserved by this registered tool.","readOnly":true},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description of the registered tool capability.","readOnly":true}},"type":"object","required":["id","registered_tool_key","registered_tool_version","order","enabled","provision_source","name","tool_names","description"],"title":"TaskAgentRegisteredToolRead","description":"Registered first-party tool association in a TaskAgent read response."},"TaskAgentRevisionRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"instruction":{"type":"string","title":"Instruction"},"mode":{"$ref":"#/components/schemas/TaskAgentMode"},"llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Llm Model Id"},"llm_model":{"anyOf":[{"$ref":"#/components/schemas/LLMModel"},{"type":"null"}]},"fallback_llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Fallback Llm Model Id"},"fallback_llm_model":{"anyOf":[{"$ref":"#/components/schemas/LLMModel"},{"type":"null"}]},"task_tools":{"items":{"$ref":"#/components/schemas/TaskAgentTaskToolRead"},"type":"array","title":"Task Tools"},"integrations":{"items":{"$ref":"#/components/schemas/TaskAgentIntegrationRead"},"type":"array","title":"Integrations"},"skills":{"items":{"$ref":"#/components/schemas/TaskAgentSkillRead"},"type":"array","title":"Skills"},"mcp_servers":{"items":{"$ref":"#/components/schemas/TaskAgentMcpServerRead"},"type":"array","title":"Mcp Servers"},"registered_tools":{"items":{"$ref":"#/components/schemas/TaskAgentRegisteredToolRead"},"type":"array","title":"Registered Tools"},"tags":{"items":{"$ref":"#/components/schemas/Tag"},"type":"array","title":"Tags"},"memory_strategy":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Memory Strategy"},"memory_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Memory Config"},"max_turns":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Max Turns"},"active":{"type":"boolean","title":"Active","default":false},"created":{"type":"string","title":"Created"},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"}},"type":"object","required":["id","task_agent_id","description","instruction","mode","llm_model_id","fallback_llm_model_id","created"],"title":"TaskAgentRevisionRead","description":"Full TaskAgent revision read schema."},"TaskAgentRevisionSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"created":{"type":"string","title":"Created"},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"}},"type":"object","required":["id","task_agent_id","created"],"title":"TaskAgentRevisionSummary","description":"Summary of the active TaskAgent revision."},"TaskAgentRunApprovalSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"status":{"$ref":"#/components/schemas/TaskAgentApprovalRequestStatus"},"tool_type":{"$ref":"#/components/schemas/TaskAgentToolSource"},"tool_name":{"type":"string","title":"Tool Name"},"requested_at":{"type":"string","title":"Requested At"},"decided_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decided At"},"requested_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Requested By User Id"},"decided_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Decided By User Id"},"decision_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Decision Note"}},"type":"object","required":["id","status","tool_type","tool_name","requested_at"],"title":"TaskAgentRunApprovalSummary","description":"Compact approval request summary embedded in TaskAgentRun responses."},"TaskAgentRunEventsResponse":{"properties":{"run_id":{"type":"string","format":"uuid","title":"Run Id","description":"ID of the TaskAgentRun."},"session_id":{"type":"string","title":"Session Id","description":"ADK session ID."},"events":{"items":{"$ref":"#/components/schemas/TaskAgentEvent"},"type":"array","title":"Events","description":"Conversation events from the session.","default":[]}},"type":"object","required":["run_id","session_id"],"title":"TaskAgentRunEventsResponse","description":"Response containing events for a TaskAgentRun."},"TaskAgentRunModelUsageRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_agent_run_id":{"type":"string","format":"uuid","title":"Task Agent Run Id"},"llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Llm Model Id"},"usage_scope":{"type":"string","enum":["reasoning","memory_compaction"],"title":"Usage Scope"},"usage_type":{"type":"string","enum":["primary","fallback"],"title":"Usage Type"},"input_tokens":{"type":"integer","title":"Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"total_tokens":{"type":"integer","title":"Total Tokens"},"charged_credits":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Charged Credits"},"call_count":{"type":"integer","title":"Call Count"},"created":{"type":"string","title":"Created"},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"}},"type":"object","required":["id","task_agent_run_id","llm_model_id","usage_scope","usage_type","input_tokens","output_tokens","total_tokens","charged_credits","call_count","created","modified"],"title":"TaskAgentRunModelUsageRead","description":"Schema for reading per-model TaskAgent run usage."},"TaskAgentRunRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id"},"session_id":{"type":"string","title":"Session Id","description":"ADK session ID (string format)."},"adk_session_user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Adk Session User Id"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id"},"actor_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor User Id","description":"User whose authority caused this run."},"actor_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Basis","description":"Reason the run actor was trusted."},"execution_surface":{"anyOf":[{"$ref":"#/components/schemas/ExecutionSurface"},{"type":"null"}],"description":"Platform surface through which execution entered."},"execution_source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Execution Source Id","description":"Surface-specific source identifier for correlating this run."},"invocation_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Invocation Id"},"invocation_ids":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Invocation Ids"},"is_continuation":{"type":"boolean","title":"Is Continuation","default":false},"primary_llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Primary Llm Model Id"},"fallback_llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Fallback Llm Model Id"},"used_fallback_model":{"type":"boolean","title":"Used Fallback Model","default":false},"primary_failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Failure Reason"},"input_tokens":{"type":"integer","title":"Input Tokens"},"output_tokens":{"type":"integer","title":"Output Tokens"},"total_tokens":{"type":"integer","title":"Total Tokens"},"charged_credits":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Charged Credits"},"total_charged_credits":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Total Charged Credits"},"created":{"type":"string","title":"Created"},"completed":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"},"status":{"$ref":"#/components/schemas/TaskAgentRunStatus"},"is_error":{"type":"boolean","title":"Is Error"},"approval_request_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Approval Request Ids","description":"IDs of approval requests linked to this TaskAgentRun."},"approval_requests":{"items":{"$ref":"#/components/schemas/TaskAgentRunApprovalSummary"},"type":"array","title":"Approval Requests","description":"Compact approval request summaries linked to this TaskAgentRun."},"had_task_tool_fail":{"type":"boolean","title":"Had Task Tool Fail","default":false},"had_mcp_tool_fail":{"type":"boolean","title":"Had Mcp Tool Fail","default":false},"had_integration_tool_fail":{"type":"boolean","title":"Had Integration Tool Fail","default":false},"task_tools_invoked":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskToolInvocationRead"},"type":"array"},{"type":"null"}],"title":"Task Tools Invoked"},"skills_activated":{"anyOf":[{"items":{"$ref":"#/components/schemas/SkillActivationRead"},"type":"array"},{"type":"null"}],"title":"Skills Activated"},"mcp_tools_invoked":{"anyOf":[{"items":{"$ref":"#/components/schemas/McpToolInvocationRead"},"type":"array"},{"type":"null"}],"title":"Mcp Tools Invoked"},"integration_tools_invoked":{"anyOf":[{"items":{"$ref":"#/components/schemas/IntegrationToolInvocationRead"},"type":"array"},{"type":"null"}],"title":"Integration Tools Invoked"},"phase_timings":{"anyOf":[{"items":{"$ref":"#/components/schemas/PhaseTimingEntry"},"type":"array"},{"type":"null"}],"title":"Phase Timings"},"context_usage":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentContextUsageRead"},{"type":"null"}]},"chaos_config":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentChaosConfig"},{"type":"null"}]},"chaos_events":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskAgentChaosEventRead"},"type":"array"},{"type":"null"}],"title":"Chaos Events"},"termination_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Termination Reason"},"last_activity_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Activity At"},"trigger_type":{"type":"string","title":"Trigger Type","description":"How the run was triggered. Non-trigger sources include manual, api, and slack; trigger executions use their trigger type value.","default":"manual"},"model_usages":{"items":{"$ref":"#/components/schemas/TaskAgentRunModelUsageRead"},"type":"array","title":"Model Usages"},"files":{"items":{"$ref":"#/components/schemas/TaskAgentFileMetadata"},"type":"array","title":"Files","description":"Files associated with this agent run (both uploaded and generated by task tools)","default":[]},"is_chaos_run":{"type":"boolean","title":"Is Chaos Run","readOnly":true}},"type":"object","required":["id","task_agent_id","session_id","user_id","input_tokens","output_tokens","total_tokens","charged_credits","created","completed","duration_ms","status","is_error","task_tools_invoked","is_chaos_run"],"title":"TaskAgentRunRead","description":"Schema for reading a TaskAgentRun."},"TaskAgentRunStatus":{"type":"string","enum":["running","waiting_for_human","completed","failed"],"title":"TaskAgentRunStatus","description":"Status of a TaskAgent run."},"TaskAgentRunSupportRequestCreate":{"properties":{"run_ids":{"items":{"type":"string","format":"uuid"},"type":"array","minItems":1,"title":"Run Ids"},"annotation":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}],"title":"Annotation"}},"additionalProperties":false,"type":"object","required":["run_ids"],"title":"TaskAgentRunSupportRequestCreate"},"TaskAgentRunSupportRequestMetadata":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"org_id":{"type":"string","format":"uuid","title":"Org Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"requested_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Requested By User Id"},"annotation":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Annotation"},"status":{"anyOf":[{"type":"string","enum":["open","redacted"]},{"type":"string"}],"title":"Status"},"payload_redacted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Payload Redacted At"},"payload_redacted_by_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Payload Redacted By User Id"},"redaction_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redaction Reason"},"created":{"type":"string","title":"Created"},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"},"snapshot_entries":{"items":{"$ref":"#/components/schemas/TaskAgentRunSupportRequestSnapshotEntry"},"type":"array","title":"Snapshot Entries"}},"type":"object","required":["id","org_id","project_id","requested_by_user_id","status","created"],"title":"TaskAgentRunSupportRequestMetadata"},"TaskAgentRunSupportRequestSnapshotEntry":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_agent_run_id":{"type":"string","format":"uuid","title":"Task Agent Run Id"},"snapshot_schema_version":{"type":"integer","title":"Snapshot Schema Version"},"payload_created_at":{"type":"string","title":"Payload Created At"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created":{"type":"string","title":"Created"},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"}},"type":"object","required":["id","task_agent_run_id","snapshot_schema_version","payload_created_at","created"],"title":"TaskAgentRunSupportRequestSnapshotEntry"},"TaskAgentRuntimeComponentContextUsage":{"properties":{"estimated_tokens":{"type":"integer","minimum":0.0,"title":"Estimated Tokens","default":0},"tool_declarations":{"$ref":"#/components/schemas/TaskAgentToolDeclarationContextUsage"},"loaded_payloads":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Loaded Payloads"},"provenance":{"additionalProperties":{"type":"integer"},"type":"object","title":"Provenance"}},"type":"object","title":"TaskAgentRuntimeComponentContextUsage"},"TaskAgentSessionDetail":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"ADK session ID (string format).","examples":["abc123"]},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"run_count":{"type":"integer","title":"Run Count","description":"Number of runs in this session."},"first_run":{"type":"string","title":"First Run"},"last_run":{"type":"string","title":"Last Run"},"total_tokens":{"type":"integer","title":"Total Tokens"},"total_charged_credits":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Charged Credits","description":"Sum of total_charged_credits across all runs in this session."},"runs":{"items":{"$ref":"#/components/schemas/TaskAgentRunRead"},"type":"array","title":"Runs","description":"Runs in this session.","default":[]}},"type":"object","required":["session_id","task_agent_id","run_count","first_run","last_run","total_tokens","total_charged_credits"],"title":"TaskAgentSessionDetail","description":"Detailed session info including individual runs."},"TaskAgentSessionSummary":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"ADK session ID (string format).","examples":["abc123"]},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"run_count":{"type":"integer","title":"Run Count","description":"Number of runs in this session."},"first_run":{"type":"string","title":"First Run"},"last_run":{"type":"string","title":"Last Run"},"total_tokens":{"type":"integer","title":"Total Tokens"},"total_charged_credits":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Charged Credits","description":"Sum of total_charged_credits across all runs in this session."}},"type":"object","required":["session_id","task_agent_id","run_count","first_run","last_run","total_tokens","total_charged_credits"],"title":"TaskAgentSessionSummary","description":"Summary of a session, derived from TaskAgentRun records + ADK session."},"TaskAgentSevenDaySummary":{"properties":{"run_count":{"type":"integer","title":"Run Count","description":"Number of visible TaskAgent runs created in the last seven days.","default":0},"average_charged_credits":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Average Charged Credits","description":"Average charged credits across visible TaskAgent runs created in the last seven days."},"average_duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Average Duration Ms","description":"Average duration in milliseconds across visible TaskAgent runs created in the last seven days."}},"type":"object","title":"TaskAgentSevenDaySummary","description":"Seven day TaskAgent run summary."},"TaskAgentShare":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"id":{"type":"string","format":"uuid","title":"Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id"},"task_agent_revision_id":{"type":"string","format":"uuid","title":"Task Agent Revision Id"},"user_id":{"type":"string","format":"uuid","title":"User Id"},"task_agent_name":{"type":"string","title":"Task Agent Name"},"short_id":{"type":"string","title":"Short Id"},"views_count":{"type":"integer","title":"Views Count"},"active":{"type":"boolean","title":"Active"},"created":{"type":"string","title":"Created"},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified"},"tags":{"items":{"$ref":"#/components/schemas/Tag"},"type":"array","title":"Tags"},"share_url":{"type":"string","title":"Share Url","readOnly":true}},"type":"object","required":["id","project_id","task_agent_id","task_agent_revision_id","user_id","task_agent_name","short_id","views_count","active","created","share_url"],"title":"TaskAgentShare","description":"Authenticated TaskAgent share response."},"TaskAgentShareCreate":{"properties":{"title":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id","description":"Optional pinned TaskAgent revision. Defaults to the active revision."},"custom_short_id":{"anyOf":[{"type":"string","maxLength":64,"minLength":3,"pattern":"^[a-zA-Z0-9_-]+$"},{"type":"null"}],"title":"Custom Short Id","description":"Optional custom public short ID."}},"type":"object","title":"TaskAgentShareCreate","description":"Request schema for creating a TaskAgent share."},"TaskAgentSkillInput":{"properties":{"skill_id":{"type":"string","format":"uuid","title":"Skill Id","description":"ID of the declarative Skill to attach."},"skill_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Skill Revision Id","description":"Pinned skill revision. None is only valid for non-capability skills; skills with capabilities must be pinned to a concrete revision."}},"type":"object","required":["skill_id"],"title":"TaskAgentSkillInput","description":"Declarative skill to attach to a TaskAgent."},"TaskAgentSkillRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"skill_id":{"type":"string","format":"uuid","title":"Skill Id"},"skill_slug":{"type":"string","title":"Skill Slug","description":"Stable kebab-case skill slug used by ADK."},"skill_display_name":{"type":"string","title":"Skill Display Name","description":"Human-readable skill display name."},"skill_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Skill Revision Id","description":"Pinned revision ID. None is only valid for non-capability skills; skills with capabilities must be pinned to a concrete revision."},"order":{"type":"integer","title":"Order","description":"Attachment order (0-indexed)."},"enabled":{"type":"boolean","title":"Enabled","description":"Whether this skill association is enabled."}},"type":"object","required":["id","skill_id","skill_slug","skill_display_name","order","enabled"],"title":"TaskAgentSkillRead","description":"Declarative skill association in a TaskAgent read response."},"TaskAgentTaskRevisionStrategy":{"type":"string","enum":["pinned","follow_active"],"title":"TaskAgentTaskRevisionStrategy","description":"How a TaskAgent task tool resolves its TaskRevision."},"TaskAgentTaskToolInput":{"properties":{"task_id":{"type":"string","format":"uuid","title":"Task Id","description":"ID of the Task to add as a task tool.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f2"]},"task_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Revision Id","description":"Optional pinned TaskRevision. When omitted, the current active TaskRevision is resolved and pinned at write time."},"revision_strategy":{"$ref":"#/components/schemas/TaskAgentTaskRevisionStrategy","description":"Revision resolution strategy. 'pinned' stores a concrete TaskRevision; 'follow_active' resolves the Task's active revision at run time.","default":"pinned"},"is_output_formatter":{"type":"boolean","title":"Is Output Formatter","description":"Mark this task tool as the output formatter. Only one task tool per agent can be marked.","default":false},"action_mode":{"$ref":"#/components/schemas/TaskAgentToolActionMode","description":"Whether this task tool auto-runs or requires approval.","default":"auto_run"},"approval_percent":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Approval Percent","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory.","default":100},"rejection_behavior":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior","description":"Behavior when a required approval is rejected.","default":"end_run"}},"type":"object","required":["task_id"],"title":"TaskAgentTaskToolInput","description":"Input schema for a task tool when creating/updating a TaskAgent."},"TaskAgentTaskToolRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_id":{"type":"string","format":"uuid","title":"Task Id"},"task_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Revision Id","description":"Pinned TaskRevision used when executing this task tool."},"revision_strategy":{"$ref":"#/components/schemas/TaskAgentTaskRevisionStrategy","description":"Revision resolution strategy for this task tool.","default":"pinned"},"task_name":{"type":"string","title":"Task Name","description":"Name of the Task linked as a task tool.","examples":["Summarize"]},"order":{"type":"integer","title":"Order","description":"Order for sequential execution.","examples":[0]},"enabled":{"type":"boolean","title":"Enabled","description":"Whether this task tool is enabled.","examples":[true]},"is_output_formatter":{"type":"boolean","title":"Is Output Formatter","description":"Whether this task tool is the output formatter.","default":false},"action_mode":{"$ref":"#/components/schemas/TaskAgentToolActionMode","default":"auto_run"},"approval_percent":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Approval Percent","description":"Percentage of calls with an effective require_approval action mode that trigger approval. Values from 1 through 99 permit calls to execute without human approval; use 100 when review is mandatory.","default":100},"rejection_behavior":{"$ref":"#/components/schemas/TaskAgentToolRejectionBehavior","default":"end_run"}},"type":"object","required":["id","task_id","task_name","order","enabled"],"title":"TaskAgentTaskToolRead","description":"Schema for reading a TaskAgent task tool."},"TaskAgentTimingBucket":{"properties":{"avg_duration_ms":{"type":"number","minimum":0.0,"title":"Avg Duration Ms","description":"Average TaskAgent run duration in milliseconds for the time bucket.","examples":[12500]},"total_runs":{"type":"integer","minimum":0.0,"title":"Total Runs","description":"Number of completed TaskAgent runs in the time bucket.","examples":[25]}},"type":"object","required":["avg_duration_ms","total_runs"],"title":"TaskAgentTimingBucket","description":"Timing metrics for a single aggregation bucket."},"TaskAgentTimingReport":{"properties":{"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id","description":"Unique identifier of the TaskAgent.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"date_range":{"additionalProperties":{"type":"string"},"type":"object","title":"Date Range","description":"Time period covered by the report.","examples":[{"end":"2024-03-15T15:00:00Z","start":"2024-03-14T15:00:00Z"}]},"aggregation":{"type":"string","enum":["hour","day"],"title":"Aggregation","description":"Time bucket granularity used for the report.","examples":["hour"]},"data":{"additionalProperties":{"$ref":"#/components/schemas/TaskAgentTimingBucket"},"type":"object","title":"Data","description":"Average duration and run counts for each aggregation bucket.","examples":[{"2024-03-14T15:00:00":{"avg_duration_ms":12500,"total_runs":25},"2024-03-14T16:00:00":{"avg_duration_ms":11800,"total_runs":30}}]}},"type":"object","required":["task_agent_id","date_range","aggregation","data"],"title":"TaskAgentTimingReport","description":"Aggregate run timing report for a TaskAgent."},"TaskAgentTokenReport":{"properties":{"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id","description":"Unique identifier of the TaskAgent.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"date_range":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object","title":"Date Range","description":"Time period covered by the report.","examples":[{"end":"2024-01-31T23:59:59Z","start":"2024-01-01T00:00:00Z"}]},"total_input_tokens":{"type":"integer","minimum":0.0,"title":"Total Input Tokens","description":"Total input tokens consumed by agent reasoning during the reporting period.","examples":[45000]},"total_output_tokens":{"type":"integer","minimum":0.0,"title":"Total Output Tokens","description":"Total output tokens produced by agent reasoning during the reporting period.","examples":[12000]},"total_tokens":{"type":"integer","minimum":0.0,"title":"Total Tokens","description":"Combined total of input and output tokens during the reporting period.","examples":[57000]},"total_runs":{"type":"integer","minimum":0.0,"title":"Total Runs","description":"Number of TaskAgent runs included in the report.","examples":[150]}},"type":"object","required":["task_agent_id","date_range","total_input_tokens","total_output_tokens","total_tokens","total_runs"],"title":"TaskAgentTokenReport","description":"Aggregate reasoning token usage for a TaskAgent."},"TaskAgentToolActionMode":{"type":"string","enum":["auto_run","require_approval"],"title":"TaskAgentToolActionMode","description":"Runtime action mode for a TaskAgent tool."},"TaskAgentToolDeclarationContextUsage":{"properties":{"estimated_tokens":{"type":"integer","minimum":0.0,"title":"Estimated Tokens","default":0},"count":{"type":"integer","minimum":0.0,"title":"Count","default":0},"unavailable_count":{"type":"integer","minimum":0.0,"title":"Unavailable Count","default":0},"error_count":{"type":"integer","minimum":0.0,"title":"Error Count","default":0}},"type":"object","title":"TaskAgentToolDeclarationContextUsage"},"TaskAgentToolRejectionBehavior":{"type":"string","enum":["end_run","return_rejection_to_model"],"title":"TaskAgentToolRejectionBehavior","description":"Behavior when a human rejects an approval-gated tool call."},"TaskAgentToolSource":{"type":"string","enum":["task","mcp","integration","registered_tool"],"title":"TaskAgentToolSource","description":"TaskAgent tool source categories for action controls."},"TaskAgentUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"instruction":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Instruction"},"mode":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentMode"},{"type":"null"}]},"llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Llm Model Id"},"fallback_llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Fallback Llm Model Id"},"task_tools":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskAgentTaskToolInput"},"type":"array"},{"type":"null"}],"title":"Task Tools","description":"Full replacement of task tools. Omit field to leave task tools unchanged. Pass empty list to remove all task tools."},"mcp_servers":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskAgentMcpServerInput"},"type":"array"},{"type":"null"}],"title":"Mcp Servers","description":"Full replacement of MCP servers. Omit field to leave unchanged. Pass empty list to remove all."},"integrations":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskAgentIntegrationInput"},"type":"array"},{"type":"null"}],"title":"Integrations","description":"Full replacement of integrations. Omit field to leave unchanged. Pass empty list to remove all."},"skills":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskAgentSkillInput"},"type":"array"},{"type":"null"}],"title":"Skills","description":"Full replacement of declarative skills. Omit field to leave unchanged. Pass empty list to remove all."},"memory_strategy":{"anyOf":[{"type":"string","enum":["sliding_window","compaction"]},{"type":"null"}],"title":"Memory Strategy"},"memory_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Memory Config"},"max_turns":{"anyOf":[{"type":"integer","maximum":500.0,"minimum":1.0},{"type":"null"}],"title":"Max Turns"},"task_agent_run_visibility":{"anyOf":[{"type":"string","enum":["owner_only","editors_and_owners","all_viewers"]},{"type":"null"}],"title":"Task Agent Run Visibility","description":"Controls who can see all TaskAgent runs for this agent."},"active_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Active Revision Id","description":"Existing TaskAgent revision to activate. Omit to leave the active revision unchanged."}},"additionalProperties":false,"type":"object","title":"TaskAgentUpdate","description":"Schema for updating a TaskAgent.\n\n``registered_tools`` are intentionally omitted from the public write\ncontract. They remain skill-managed and internal-only."},"TaskAgentUsageReport":{"properties":{"task_agent_id":{"type":"string","format":"uuid","title":"Task Agent Id","description":"Unique identifier of the TaskAgent.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"date_range":{"additionalProperties":{"type":"string"},"type":"object","title":"Date Range","description":"Time period covered by the report.","examples":[{"end":"2024-03-17T00:00:00Z","start":"2024-03-10T00:00:00Z"}]},"aggregation":{"type":"string","enum":["day","week"],"title":"Aggregation","description":"Time bucket granularity used for the report.","examples":["day"]},"status":{"$ref":"#/components/schemas/UsageReportStatus","description":"Run outcome filter applied to the report.","examples":["ALL"]},"data":{"additionalProperties":{"type":"integer"},"type":"object","title":"Data","description":"Run counts for each aggregation bucket.","examples":[{"2024-03-10T00:00:00":45,"2024-03-11T00:00:00":52,"2024-03-12T00:00:00":38}]},"total_runs":{"type":"integer","minimum":0.0,"title":"Total Runs","description":"Total number of runs included in the report.","examples":[135]}},"type":"object","required":["task_agent_id","date_range","aggregation","status","data","total_runs"],"title":"TaskAgentUsageReport","description":"Aggregate run counts over time for a TaskAgent."},"TaskCreate":{"properties":{"system_prompt":{"type":"string","title":"System Prompt","description":"The system prompt that is used to set the LLM context."},"user_prompt":{"type":"string","title":"User Prompt","description":"The description of the Task. It is not required to mention the outputs in the prompt, but it can help the model to understand the context better. Any input strings should be referenced with the dynamic `{...}` syntax, this informs the model to look for those values in the input data."},"llm_model_id":{"type":"string","format":"uuid","title":"Llm Model Id","description":"The LLM model to use for the Task."},"llm_config":{"additionalProperties":true,"type":"object","title":"Llm Config","description":"Specific configuration parameters for the LLM model."},"output_format":{"anyOf":[{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/TagOutputFormat-Input"},{"type":"string","enum":["str","string","boolean","bool","int","integer","list","object","number"]}]},"type":"object"},{"type":"null"}],"title":"Output Format","description":"This gives control over the structure of how the Task responds. Supports shorthand notation or an object with `type` can be specified for each attribute. In most instances, the LLM will be able to generate the desired output into the relevant property, but an optional `description` can be passed to provide it with additional context."},"task_forwarder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Forwarder Id","description":"The unique identifier for a valid Task Forwarder. It is used to forward the Task output to another system or service."},"rag":{"anyOf":[{"$ref":"#/components/schemas/TaskRAG"},{"type":"null"}],"description":"**Note: This is a Paid Tier feature.** Provide additional domain specific input to the LLM so that it is able to reference user specific information when executing the Task. Examples of this could be a product catalogue, terms and conditions or a user manual."},"file_input_mode":{"$ref":"#/components/schemas/FileInputMode","description":"Specifies what file types are accepted for visual LLM processing. Values: 'none' (default), 'image', 'pdf', 'image_or_pdf', 'any'.","default":"none"},"optimise_images":{"type":"boolean","title":"Optimise Images","description":"When `true` (default) images will be automatically optimised before processing. Set to `false` to disable lossy image optimisation.","default":true},"test":{"type":"boolean","title":"Test","description":"True if revision is a test revision. Test revisions cannot be live and are used for rapid Task testing/iteration.","default":false},"input_processors":{"items":{"$ref":"#/components/schemas/TaskInputProcessor"},"type":"array","title":"Input Processors","default":[]},"annotation":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Annotation","description":"Optional note or comment about this revision. Useful for tracking changes, experiments, or the purpose of test revisions.","examples":["Testing higher temperature","Production v2","A/B test variant"]},"fallback_llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Fallback Llm Model Id","description":"The LLM model to use as fallback if the primary model fails."},"fallback_llm_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Fallback Llm Config","description":"Specific configuration parameters for the fallback LLM model."},"tool_choice":{"anyOf":[{"$ref":"#/components/schemas/TaskToolChoiceEnum"},{"type":"null"}],"description":"Tool invocation mode when runtime tools are attached."},"task_mcp_tool_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Mcp Tool Ids","description":"Task MCP tool IDs attached to this revision."},"integration_tool_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Integration Tool Ids","description":"Integration tool IDs attached to this revision.","deprecated":true},"integration_bindings":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskIntegrationBindingInput"},"type":"array"},{"type":"null"}],"title":"Integration Bindings"},"name":{"type":"string","maxLength":63,"pattern":"^[a-zA-Z0-9\\- ]+$","title":"Name","description":"A name or reference for the Task."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"A longer description of the Task for internal reference."},"enabled":{"type":"boolean","title":"Enabled","description":"When `true` the Task is active and callable. `false` denotes the Task is not yet operational."},"public":{"type":"boolean","title":"Public","description":"When `true` the Task is public and can be accessed by any User.","default":false},"exposed_to_agents":{"type":"boolean","title":"Exposed To Agents","description":"When `true` the Task is accessible to agents through the unauthenticated agent endpoint.","default":false},"output_modality":{"$ref":"#/components/schemas/OutputModality","description":"Specifies the output modality of the task. Can be 'json', 'image', 'audio', 'pdf', 'text', or 'csv'. Defaults to 'json'.","default":"json"},"task_run_visibility":{"type":"string","enum":["owner_only","editors_and_owners","all_viewers"],"title":"Task Run Visibility","description":"Controls who can view all task runs. 'owner_only' - only task owners see all runs (default), 'editors_and_owners' - task editors and owners see all runs, 'all_viewers' - all users with view permission see all runs.","default":"owner_only"},"tags":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Tags"},"revision_tags":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Revision Tags"}},"type":"object","required":["system_prompt","user_prompt","llm_model_id","name","enabled"],"title":"TaskCreate","example":{"annotation":"Production v2 - Added image matching capability","description":"A task to pre-triage user onboarding before IDV.","enabled":true,"input_processors":[{"config":{"extract_text":true,"include_title":true,"max_length":5000},"input_processor":"url_scraper","param_name":"description"}],"llm_config":{"temperature":0.7},"llm_model_id":"019011e6-e530-3aca-6cf7-2973387c255d","name":"Fintech Pre-Triage","optimise_images":true,"output_format":{"compliance":"bool","hint":{"type":"str"},"match":{"description":"True if the provided description is a close match","type":"bool"},"rationale":"str"},"rag":{"collection_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","rag_config":{"candidate_k":12,"final_k":5,"include_sources":true,"max_context_chunks":5,"max_context_tokens":4000,"rewrite_mode":"single_query"}},"system_prompt":"You are an expert software program specifically designed for the fintech industry that will be used for pre-triage tasks to ensure the best possible client UX and efficient 3rd party platform interoperability.","task_forwarder_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","test":false,"user_prompt":"Your task is to validate the uploaded image and determine whether it will be suitable for authentication and onboarding checks. If the image of the person is clear and typical of a passport style photo then set the compliance field to true. Provide rationale for your decision in the rationale field. If the compliance result is false, then provide a helpful hint for the customer who has submitted the photo informing them why it is unacceptable and some steps to remedy it, place this into the hint field. Determine whether the following description matches the provided image: {description}"}},"TaskForwarder":{"oneOf":[{"$ref":"#/components/schemas/WebhookForwarderInDB"},{"$ref":"#/components/schemas/EmailForwarderInDB"}]},"TaskForwarderConfig":{"properties":{"destination_url":{"type":"string","title":"Destination Url","description":"The URL where Task Run result will be forwarded. Must be a valid HTTPS URL."}},"type":"object","required":["destination_url"],"title":"TaskForwarderConfig"},"TaskForwarderEmailConfig":{"properties":{"recipient_emails":{"items":{"type":"string","format":"email"},"type":"array","minItems":1,"title":"Recipient Emails","description":"List of email addresses to send task results to."},"subject_template":{"type":"string","title":"Subject Template","description":"Email subject template with {variable} placeholders for task data."},"body_template":{"type":"string","title":"Body Template","description":"Email body template with {variable} placeholders for task data."},"cc_emails":{"anyOf":[{"items":{"type":"string","format":"email"},"type":"array"},{"type":"null"}],"title":"Cc Emails","description":"Optional list of CC email addresses."},"bcc_emails":{"anyOf":[{"items":{"type":"string","format":"email"},"type":"array"},{"type":"null"}],"title":"Bcc Emails","description":"Optional list of BCC email addresses."}},"type":"object","required":["recipient_emails","subject_template","body_template"],"title":"TaskForwarderEmailConfig"},"TaskForwarderSensitiveConfig":{"properties":{"signing_key":{"type":"string","title":"Signing Key","description":"A secret key used to sign the forwarded data for verification purposes."}},"type":"object","required":["signing_key"],"title":"TaskForwarderSensitiveConfig"},"TaskForwarderTypeInfo":{"properties":{"type":{"type":"string","title":"Type","description":"The forwarder type identifier (e.g., 'webhook', 'email')"},"name":{"type":"string","title":"Name","description":"Human-readable name for the forwarder type"},"description":{"type":"string","title":"Description","description":"Description of what this forwarder type does"},"config_schema":{"additionalProperties":true,"type":"object","title":"Config Schema","description":"JSON Schema for the forwarder's configuration"},"config_sensitive_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config Sensitive Schema","description":"JSON Schema for the forwarder's sensitive configuration (if any). Will be encrypted within the application."}},"type":"object","required":["type","name","description","config_schema"],"title":"TaskForwarderTypeInfo"},"TaskIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of task roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of task roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"TaskIAMMemberRoleUpdate"},"TaskIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","edit","remove_editor","remove_member","remove_owner","run_task","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the task."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"TaskIAMPermissionTest"},"TaskInputProcessor":{"properties":{"param_name":{"type":"string","title":"Param Name"},"input_processor":{"type":"string","title":"Input Processor"},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config"}},"type":"object","required":["param_name","input_processor"],"title":"TaskInputProcessor"},"TaskIntegrationBindingInput":{"properties":{"binding_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Binding Id","description":"Source revision binding to inherit when creating a revision."},"project_integration_id":{"type":"string","format":"uuid","title":"Project Integration Id"},"integration_tool_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Integration Tool Ids"},"credential_policy":{"anyOf":[{"$ref":"#/components/schemas/IntegrationCredentialPolicy"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["project_integration_id"],"title":"TaskIntegrationBindingInput"},"TaskIntegrationBindingRead":{"properties":{"binding_id":{"type":"string","format":"uuid","title":"Binding Id"},"project_integration_id":{"type":"string","format":"uuid","title":"Project Integration Id"},"integration_tool_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Integration Tool Ids"},"credential_policy":{"$ref":"#/components/schemas/IntegrationCredentialPolicy"}},"additionalProperties":false,"type":"object","required":["binding_id","project_integration_id","credential_policy"],"title":"TaskIntegrationBindingRead"},"TaskMcpAuthStrategy":{"type":"string","enum":["bearer","api_key_header"],"title":"TaskMcpAuthStrategy"},"TaskMcpAuthType":{"type":"string","enum":["none","oauth","api_key"],"title":"TaskMcpAuthType"},"TaskMcpServer":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"server_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Server Url"},"enabled":{"type":"boolean","title":"Enabled","default":true},"id":{"type":"string","format":"uuid","title":"Id"},"catalog_server_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Catalog Server Id"},"catalog_server_slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Catalog Server Slug"},"canonical_resource":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Canonical Resource"},"transport":{"$ref":"#/components/schemas/TaskMcpTransport"},"auth_state":{"type":"string","enum":["connected","expired","reauth_required","none"],"title":"Auth State"},"auth_state_reason":{"anyOf":[{"type":"string","enum":["no_refresh_token","token_refresh_failed","credentials_rejected","server_unreachable"]},{"type":"null"}],"title":"Auth State Reason"},"auth_type":{"$ref":"#/components/schemas/TaskMcpAuthType"},"auth_strategy":{"anyOf":[{"$ref":"#/components/schemas/TaskMcpAuthStrategy"},{"type":"null"}]},"auth_header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Header Name"},"project_id":{"type":"string","format":"uuid","title":"Project Id"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"additionalProperties":false,"type":"object","required":["name","server_url","id","canonical_resource","transport","auth_state","auth_type","project_id","created","modified"],"title":"TaskMcpServer"},"TaskMcpServerCatalogRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"slug":{"type":"string","title":"Slug"},"display_name":{"type":"string","title":"Display Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"canonical_resource":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Canonical Resource"},"default_server_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Default Server Url"},"default_transport":{"$ref":"#/components/schemas/TaskMcpTransport"},"auth_mode":{"type":"string","enum":["none","oauth","api_key","oauth_or_api_key"],"title":"Auth Mode"},"enabled":{"type":"boolean","title":"Enabled"}},"type":"object","required":["id","slug","display_name","canonical_resource","default_server_url","default_transport","auth_mode","enabled"],"title":"TaskMcpServerCatalogRead"},"TaskMcpServerCreate":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"server_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Server Url"},"enabled":{"type":"boolean","title":"Enabled","default":true},"auth_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Session Id"},"api_key":{"anyOf":[{"type":"string","format":"password","writeOnly":true},{"type":"null"}],"title":"Api Key"},"api_key_strategy":{"anyOf":[{"$ref":"#/components/schemas/TaskMcpAuthStrategy"},{"type":"null"}]},"api_key_header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Header Name"},"transport":{"anyOf":[{"$ref":"#/components/schemas/TaskMcpTransport"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["name","server_url"],"title":"TaskMcpServerCreate"},"TaskMcpServerUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled"},"auth_session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Session Id"},"api_key":{"anyOf":[{"type":"string","format":"password","writeOnly":true},{"type":"null"}],"title":"Api Key"},"api_key_strategy":{"anyOf":[{"$ref":"#/components/schemas/TaskMcpAuthStrategy"},{"type":"null"}]},"api_key_header_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Header Name"}},"additionalProperties":false,"type":"object","title":"TaskMcpServerUpdate"},"TaskMcpTool":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"task_mcp_server_id":{"type":"string","format":"uuid","title":"Task Mcp Server Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"tool_name":{"type":"string","title":"Tool Name"},"tool_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tool Description"},"tool_input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Tool Input Schema"},"safe_tool_name":{"type":"string","title":"Safe Tool Name"},"tool_timeout_seconds":{"type":"integer","title":"Tool Timeout Seconds"},"enabled":{"type":"boolean","title":"Enabled"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"type":"object","required":["id","task_mcp_server_id","name","tool_name","safe_tool_name","tool_timeout_seconds","enabled","created","modified"],"title":"TaskMcpTool"},"TaskMcpToolBulkCreate":{"properties":{"task_mcp_server_id":{"type":"string","format":"uuid","title":"Task Mcp Server Id"},"tools":{"items":{"$ref":"#/components/schemas/TaskMcpToolBulkItem"},"type":"array","maxItems":50,"minItems":1,"title":"Tools"}},"additionalProperties":false,"type":"object","required":["task_mcp_server_id","tools"],"title":"TaskMcpToolBulkCreate"},"TaskMcpToolBulkItem":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"tool_name":{"type":"string","maxLength":255,"minLength":1,"title":"Tool Name"},"enabled":{"type":"boolean","title":"Enabled","default":true}},"additionalProperties":false,"type":"object","required":["name","tool_name"],"title":"TaskMcpToolBulkItem"},"TaskMcpToolCreate":{"properties":{"name":{"type":"string","maxLength":255,"minLength":1,"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"tool_name":{"type":"string","maxLength":255,"minLength":1,"title":"Tool Name"},"enabled":{"type":"boolean","title":"Enabled","default":true},"task_mcp_server_id":{"type":"string","format":"uuid","title":"Task Mcp Server Id"}},"type":"object","required":["name","tool_name","task_mcp_server_id"],"title":"TaskMcpToolCreate"},"TaskMcpToolUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled"}},"type":"object","title":"TaskMcpToolUpdate"},"TaskMcpTransport":{"type":"string","enum":["streamable_http","sse"],"title":"TaskMcpTransport"},"TaskRAG":{"properties":{"collection_id":{"type":"string","format":"uuid","title":"Collection Id"},"rag_config":{"anyOf":[{"$ref":"#/components/schemas/TaskRAGConfig"},{"type":"null"}]}},"type":"object","required":["collection_id"],"title":"TaskRAG"},"TaskRAGConfig":{"properties":{"rewrite_mode":{"type":"string","enum":["none","single_query","multi_query"],"title":"Rewrite Mode","default":"single_query"},"candidate_k":{"type":"integer","maximum":50.0,"minimum":1.0,"title":"Candidate K","default":12},"final_k":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Final K","default":5},"include_sources":{"type":"boolean","title":"Include Sources","default":true},"max_context_tokens":{"type":"integer","maximum":16000.0,"minimum":256.0,"title":"Max Context Tokens","default":4000},"max_context_chunks":{"type":"integer","maximum":20.0,"minimum":1.0,"title":"Max Context Chunks","default":5},"context_instruction":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Context Instruction"}},"type":"object","title":"TaskRAGConfig"},"TaskRecentRunsSummary":{"properties":{"task_id":{"type":"string","format":"uuid","title":"Task Id","description":"The unique identifier of the Task."},"task_name":{"type":"string","title":"Task Name","description":"Name of the Task."},"recent_runs":{"items":{"$ref":"#/components/schemas/ProjectTaskRecentRunSummary"},"type":"array","title":"Recent Runs","description":"Recent visible Task Runs for this Task, newest first."}},"type":"object","required":["task_id","task_name","recent_runs"],"title":"TaskRecentRunsSummary"},"TaskRevision":{"properties":{"system_prompt":{"type":"string","title":"System Prompt","description":"The system prompt that is used to set the LLM context."},"user_prompt":{"type":"string","title":"User Prompt","description":"The description of the Task. It is not required to mention the outputs in the prompt, but it can help the model to understand the context better. Any input strings should be referenced with the dynamic `{...}` syntax, this informs the model to look for those values in the input data."},"llm_model_id":{"type":"string","format":"uuid","title":"Llm Model Id","description":"The LLM model to use for the Task."},"llm_config":{"additionalProperties":true,"type":"object","title":"Llm Config","description":"Specific configuration parameters for the LLM model."},"output_format":{"anyOf":[{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/TagOutputFormat-Output"},{"type":"string","enum":["str","string","boolean","bool","int","integer","list","object","number"]}]},"type":"object"},{"type":"null"}],"title":"Output Format","description":"This gives control over the structure of how the Task responds. Supports shorthand notation or an object with `type` can be specified for each attribute. In most instances, the LLM will be able to generate the desired output into the relevant property, but an optional `description` can be passed to provide it with additional context."},"task_forwarder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Forwarder Id","description":"The unique identifier for a valid Task Forwarder. It is used to forward the Task output to another system or service."},"rag":{"anyOf":[{"$ref":"#/components/schemas/TaskRAG"},{"type":"null"}],"description":"**Note: This is a Paid Tier feature.** Provide additional domain specific input to the LLM so that it is able to reference user specific information when executing the Task. Examples of this could be a product catalogue, terms and conditions or a user manual."},"file_input_mode":{"$ref":"#/components/schemas/FileInputMode","description":"Specifies what file types are accepted for visual LLM processing. Values: 'none' (default), 'image', 'pdf', 'image_or_pdf', 'any'.","default":"none"},"optimise_images":{"type":"boolean","title":"Optimise Images","description":"When `true` (default) images will be automatically optimised before processing. Set to `false` to disable lossy image optimisation.","default":true},"test":{"type":"boolean","title":"Test","description":"True if revision is a test revision. Test revisions cannot be live and are used for rapid Task testing/iteration.","default":false},"input_processors":{"items":{"$ref":"#/components/schemas/TaskInputProcessor"},"type":"array","title":"Input Processors","default":[]},"annotation":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Annotation","description":"Optional note or comment about this revision. Useful for tracking changes, experiments, or the purpose of test revisions.","examples":["Testing higher temperature","Production v2","A/B test variant"]},"fallback_llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Fallback Llm Model Id","description":"The LLM model to use as fallback if the primary model fails."},"fallback_llm_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Fallback Llm Config","description":"Specific configuration parameters for the fallback LLM model."},"tool_choice":{"anyOf":[{"$ref":"#/components/schemas/TaskToolChoiceEnum"},{"type":"null"}],"description":"Tool invocation mode when runtime tools are attached."},"task_mcp_tool_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Task Mcp Tool Ids","description":"Task MCP tool IDs attached to this revision."},"integration_tool_ids":{"items":{"type":"string","format":"uuid"},"type":"array","title":"Integration Tool Ids","description":"Integration tool IDs attached to this revision.","deprecated":true},"integration_bindings":{"items":{"$ref":"#/components/schemas/TaskIntegrationBindingRead"},"type":"array","title":"Integration Bindings"},"id":{"type":"string","format":"uuid","title":"Id","description":"The unique identifier of the Revision."},"created":{"type":"string","title":"Created","description":"When the Task was created."},"modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Modified","description":"When the Task was last updated."},"active":{"type":"boolean","title":"Active","description":"When `true` the Revision is the currently active version and will be activated when the Task Run is executed.","default":false},"tags":{"items":{"$ref":"#/components/schemas/Tag"},"type":"array","title":"Tags","default":[]},"llm_model":{"$ref":"#/components/schemas/LLMModel"},"fallback_llm_model":{"anyOf":[{"$ref":"#/components/schemas/LLMModel"},{"type":"null"}]},"input_params":{"items":{"type":"string"},"type":"array","title":"Input Params","description":"A list of all the dynamic input parameters that are detected from the user prompt.","readOnly":true}},"type":"object","required":["system_prompt","user_prompt","llm_model_id","id","created","modified","llm_model","input_params"],"title":"TaskRevision","example":{"annotation":"Production v2 - Added image matching capability","description":"A task to pre-triage user onboarding before IDV.","enabled":true,"input_processors":[{"config":{"extract_text":true,"include_title":true,"max_length":5000},"input_processor":"url_scraper","param_name":"description"}],"llm_config":{"temperature":0.7},"llm_model_id":"019011e6-e530-3aca-6cf7-2973387c255d","name":"Fintech Pre-Triage","optimise_images":true,"output_format":{"compliance":"bool","hint":{"type":"str"},"match":{"description":"True if the provided description is a close match","type":"bool"},"rationale":"str"},"rag":{"collection_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","rag_config":{"candidate_k":12,"final_k":5,"include_sources":true,"max_context_chunks":5,"max_context_tokens":4000,"rewrite_mode":"single_query"}},"system_prompt":"You are an expert software program specifically designed for the fintech industry that will be used for pre-triage tasks to ensure the best possible client UX and efficient 3rd party platform interoperability.","task_forwarder_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","test":false,"user_prompt":"Your task is to validate the uploaded image and determine whether it will be suitable for authentication and onboarding checks. If the image of the person is clear and typical of a passport style photo then set the compliance field to true. Provide rationale for your decision in the rationale field. If the compliance result is false, then provide a helpful hint for the customer who has submitted the photo informing them why it is unacceptable and some steps to remedy it, place this into the hint field. Determine whether the following description matches the provided image: {description}"}},"TaskRun":{"properties":{"task_id":{"type":"string","format":"uuid","title":"Task Id","description":"The unique identifier of the Task associated with this run."},"task_revision_id":{"type":"string","format":"uuid","title":"Task Revision Id","description":"The unique identifier of the Task Revision associated with this run."},"model_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Name","description":"Name of the LLM model associated with the task revision used for this run."},"task_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Name","description":"Name of the task associated with this run."},"output_modality":{"anyOf":[{"$ref":"#/components/schemas/OutputModality"},{"type":"null"}],"description":"Output modality configured on the associated task."},"response":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"}],"title":"Response","description":"The structured response from the Task execution."},"run_data":{"properties":{"submitted":{"type":"object","description":"The input parameters provided when executing the Task."}},"additionalProperties":true,"type":"object","title":"Run Data","description":"Additional data about the Task execution, including submitted inputs. `submitted` is absent on runs that failed before their input was recorded, so the object can be empty.","example":{"submitted":{"description":"brown hair, blue sweater","image":"profile_photo.jpg"}}},"files":{"items":{"$ref":"#/components/schemas/TaskRunFileMetadata"},"type":"array","title":"Files","description":"List of file metadata objects with enriched information including download URLs.","default":[],"examples":[[{"content_type":"application/pdf","download_url":"/org/.../project/.../task/.../run/.../file/b4a66744...pdf","original_filename":"contract.pdf","size_bytes":1024576,"stored_filename":"b4a66744-6e99-4ad4-8aff-4d953bb0b9cf.pdf"}]]},"is_error":{"type":"boolean","title":"Is Error","default":false},"llm_retries":{"type":"integer","title":"Llm Retries","description":"Number of retry attempts made during LLM execution.","default":0,"examples":[0,2]},"used_fallback_model":{"type":"boolean","title":"Used Fallback Model","description":"Whether the fallback model was used","default":false},"primary_failure_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Primary Failure Reason","description":"Reason the primary model failed"},"fallback_llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Fallback Llm Model Id","description":"Fallback model that was used"},"user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"User Id","description":"The unique identifier of the User who executed the task.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"reporting_group_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Reporting Group Id","description":"The ID of the reporting group to associate with this task run"},"reference":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Reference","description":"An optional reference identifier for this task run"},"context_id":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Context Id","description":"An optional context ID for grouping related task runs"},"id":{"type":"string","format":"uuid","title":"Id","description":"The unique identifier of the Task Run."},"actor_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor User Id","description":"User whose authority caused this run."},"actor_basis":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Basis","description":"Reason the run actor was trusted."},"execution_surface":{"anyOf":[{"$ref":"#/components/schemas/ExecutionSurface"},{"type":"null"}],"description":"Platform surface through which execution entered."},"execution_source_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Execution Source Id","description":"Surface-specific source identifier for correlating this run."},"created":{"type":"string","title":"Created","description":"The timestamp when the Task Run was created."},"input_tokens":{"type":"integer","title":"Input Tokens","description":"The number of tokens submit as input to the model."},"output_tokens":{"type":"integer","title":"Output Tokens","description":"The number of tokens generated and output by the model."},"total_tokens":{"type":"integer","title":"Total Tokens","description":"The total token usage for the TaskRun."},"input_processor_timing":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Input Processor Timing","description":"The execution time for the TaskRun in seconds."},"rag_retrieval_timing":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rag Retrieval Timing","description":"The task RAG retrieval time in seconds."},"rag_query_rewrite_input_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rag Query Rewrite Input Tokens","description":"Input tokens used by the task RAG query rewrite model."},"rag_query_rewrite_output_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rag Query Rewrite Output Tokens","description":"Output tokens used by the task RAG query rewrite model."},"rag_query_rewrite_total_tokens":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rag Query Rewrite Total Tokens","description":"Total tokens used by the task RAG query rewrite model."},"llm_call_timing":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Llm Call Timing","description":"The execution time for the TaskRun in seconds."},"mcp_tool_timing":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Mcp Tool Timing","description":"Total time spent waiting on MCP tool calls in seconds."},"charged_credits":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Charged Credits","description":"The total credits charged for the TaskRun."},"input_processor_charged_credits":{"anyOf":[{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$"},{"type":"null"}],"title":"Input Processor Charged Credits","description":"Credits charged for input processor work during this task run."},"reporting_group":{"anyOf":[{"$ref":"#/components/schemas/ReportingGroup"},{"type":"null"}],"description":"The reporting group associated with this task run"},"event_trigger_id":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Event Trigger Id","description":"Webhook trigger event IDs associated with this TaskRun, if any."}},"type":"object","required":["task_id","task_revision_id","response","run_data","id","created","input_tokens","output_tokens","total_tokens","input_processor_timing","llm_call_timing","charged_credits"],"title":"TaskRun","example":{"charged_credits":"2.82","created":"2024-07-11T14:31:21.989219","files":[{"content_type":"image/jpeg","download_url":"/org/018936f0.../project/01910ec3.../task/019011e6.../run/0190a234.../file/a1b2c3d4-5e6f-7890-abcd-ef1234567890.jpg","original_filename":"profile_photo.jpg","size_bytes":524288,"stored_filename":"a1b2c3d4-5e6f-7890-abcd-ef1234567890.jpg"}],"id":"0190a234-cb74-6342-dec6-4be8f73f0c9f","input_processor_timing":0.35,"input_tokens":295,"llm_call_timing":2.45,"mcp_tool_timing":0.82,"output_tokens":58,"response":{"compliance":false,"hint":"The image is not suitable for authentication and onboarding checks. Please ensure the photo is a clear, passport-style image with a plain background, good lighting, and no accessories like sunglasses.","match":false,"rationale":"The image does not meet the requirements for a passport-style photo. The person is wearing sunglasses, and the background is not plain."},"run_data":{"submitted":{"description":"brown hair, blue sweater","image":"profile_photo.jpg"}},"task_id":"019011e6-e530-3aca-6cf7-2973387c255d","task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","total_tokens":353}},"TaskRunCreditReport":{"properties":{"task_id":{"type":"string","format":"uuid","title":"Task Id","description":"The unique identifier of the Task.","examples":["019011e6-e530-3aca-6cf7-2973387c255d"]},"task_revisions":{"items":{"$ref":"#/components/schemas/TaskRunRevisionCreditReport"},"type":"array","title":"Task Revisions","description":"Timing data broken down by task revision, showing performance metrics for each active revision."},"total_credits":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Credits","description":"Total credits charged for the Task.","examples":["100.00"]},"total_task_runs":{"type":"integer","title":"Total Task Runs","description":"Total number of task runs for each time interval.","examples":[12]},"date_range":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object","title":"Date Range","description":"The time range for the report, with start and end timestamps.","examples":[{"end":"2024-03-15T15:00:00+00:00","start":"2024-03-14T15:00:00+00:00"}]}},"type":"object","required":["task_id","task_revisions","total_credits","total_task_runs","date_range"],"title":"TaskRunCreditReport"},"TaskRunFileMetadata":{"properties":{"original_filename":{"type":"string","title":"Original Filename","description":"The original filename as submitted by the user","examples":["contract.pdf","photo.jpg"]},"stored_filename":{"type":"string","title":"Stored Filename","description":"The generated filename used for storage","examples":["b4a66744-6e99-4ad4-8aff-4d953bb0b9cf.pdf"]},"content_type":{"type":"string","title":"Content Type","description":"MIME type of the file","examples":["application/pdf","image/jpeg"]},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url","description":"Relative URL to download the file (generated dynamically, not stored in database)","examples":["/org/abc123.../project/def456.../task/ghi789.../run/jkl012.../file/b4a66744-6e99-4ad4-8aff-4d953bb0b9cf.pdf"]},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size Bytes","description":"File size in bytes (if available)","examples":[1024576]}},"type":"object","required":["original_filename","stored_filename","content_type"],"title":"TaskRunFileMetadata","description":"Metadata for files submitted/generated during task execution.","example":{"content_type":"application/pdf","download_url":"/org/abc/project/def/task/ghi/run/jkl/file/b4a66744-6e99-4ad4-8aff-4d953bb0b9cf.pdf","original_filename":"my-document.pdf","size_bytes":1024576,"stored_filename":"b4a66744-6e99-4ad4-8aff-4d953bb0b9cf.pdf"}},"TaskRunRevisionCreditReport":{"properties":{"task_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"test"}],"title":"Task Revision Id","description":"The unique identifier of the Task Revision, or 'test' for test revisions.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1","test"]},"reporting_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reporting Group","description":"The name of the reporting group, or 'ungrouped' if no reporting group is assigned. Only present when grouping by reporting groups.","examples":["batch_processing","test_runs","ungrouped"]},"total_credits":{"type":"string","pattern":"^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$","title":"Total Credits","description":"Total credits charged for the Task Revision.","examples":["100.00"]},"total_task_runs":{"type":"integer","title":"Total Task Runs","description":"Total number of task runs for this revision."}},"type":"object","required":["task_revision_id","total_credits","total_task_runs"],"title":"TaskRunRevisionCreditReport","example":{"reporting_group":"batch_processing","task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","total_credits":"100.00","total_task_runs":12}},"TaskRunRevisionTimingReport":{"properties":{"task_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"test"}],"title":"Task Revision Id","description":"The unique identifier of the Task Revision, or 'test' for test revisions.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1","test"]},"data":{"additionalProperties":true,"type":"object","title":"Data","description":"Timing data for each time interval, containing average LLM call timing and total task runs.","examples":[{"2024-03-14T15:00:00":{"avg_llm_call_timing":2.45,"total_task_runs":150}}]}},"type":"object","required":["task_revision_id","data"],"title":"TaskRunRevisionTimingReport","example":{"aggregation":"hour","date_range":{"end":"2024-03-15T15:00:00+00:00","start":"2024-03-14T15:00:00+00:00"},"task_id":"019011e6-e530-3aca-6cf7-2973387c255d","task_revisions":[{"data":{"2024-03-14T15:00:00":{"avg_llm_call_timing":2.45,"total_task_runs":150},"2024-03-14T16:00:00":{"avg_llm_call_timing":2.38,"total_task_runs":165}},"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1"}],"total_task_runs":{"2024-03-14T15:00:00":150,"2024-03-14T16:00:00":165}}},"TaskRunRevisionTokenReport":{"properties":{"task_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"test"}],"title":"Task Revision ID","description":"Unique identifier of the task revision, or 'test' for test revisions","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1","test"]},"reporting_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reporting Group","description":"The name of the reporting group, or None if no reporting group is assigned. Only present when grouping by reporting groups.","examples":["batch_processing","test_runs",null]},"total_input_tokens":{"type":"integer","minimum":0.0,"title":"Total Input Tokens","description":"Total number of input tokens consumed by this revision during the reporting period","examples":[6000]},"total_output_tokens":{"type":"integer","minimum":0.0,"title":"Total Output Tokens","description":"Total number of output tokens generated by this revision during the reporting period","examples":[3000]},"total_tokens":{"type":"integer","minimum":0.0,"title":"Total Tokens","description":"Combined total of input and output tokens for this revision","examples":[9000]},"total_task_runs":{"type":"integer","minimum":0.0,"title":"Total Task Runs","description":"Number of times this revision was executed during the reporting period","examples":[60]}},"type":"object","required":["task_revision_id","total_input_tokens","total_output_tokens","total_tokens","total_task_runs"],"title":"TaskRunRevisionTokenReport","description":"Token usage report for a specific task revision.\n\nThis model represents detailed token consumption statistics for a single task revision,\nincluding input, output, and total token counts along with execution counts.","example":{"reporting_group":"batch_processing","task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","total_input_tokens":6000,"total_output_tokens":3000,"total_task_runs":60,"total_tokens":9000}},"TaskRunRevisionUsageReport":{"properties":{"task_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","const":"test"}],"title":"Task Revision Id","description":"The unique identifier of the Task Revision, or 'test' for test revisions.","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1","test"]},"data":{"additionalProperties":{"type":"integer"},"type":"object","title":"Data","description":"Usage counts for each time interval.","examples":[{"2024-03-14T15:00:00":150,"2024-03-14T16:00:00":165}]}},"type":"object","required":["task_revision_id","data"],"title":"TaskRunRevisionUsageReport","example":{"aggregation":"day","date_range":{"end":"2024-03-15T15:00:00+00:00","start":"2024-03-14T15:00:00+00:00"},"task_id":"019011e6-e530-3aca-6cf7-2973387c255d","task_revisions":[{"data":{"2024-03-14T15:00:00":150,"2024-03-14T16:00:00":165},"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1"}],"total_counts":{"2024-03-14T15:00:00":150,"2024-03-14T16:00:00":165}}},"TaskRunTimingReport":{"properties":{"task_id":{"type":"string","format":"uuid","title":"Task Id","description":"The unique identifier of the Task.","examples":["019011e6-e530-3aca-6cf7-2973387c255d"]},"date_range":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object","title":"Date Range","description":"The time range for the report, with start and end timestamps.","examples":[{"end":"2024-03-15T15:00:00+00:00","start":"2024-03-14T15:00:00+00:00"}]},"aggregation":{"type":"string","enum":["hour","day"],"title":"Aggregation","description":"The time interval for data aggregation. 'hour' shows last 24 hours in hourly blocks, 'day' shows last 7 days in daily blocks.","examples":["hour","day"]},"total_task_runs":{"additionalProperties":{"type":"integer"},"type":"object","title":"Total Task Runs","description":"Total number of task runs for each time interval.","examples":[{"2024-03-14T15:00:00":150,"2024-03-14T16:00:00":165}]},"task_revisions":{"items":{"$ref":"#/components/schemas/TaskRunRevisionTimingReport"},"type":"array","title":"Task Revisions","description":"Timing data broken down by task revision, showing performance metrics for each active revision."}},"type":"object","required":["task_id","date_range","aggregation","total_task_runs","task_revisions"],"title":"TaskRunTimingReport","example":{"aggregation":"hour","date_range":{"end":"2024-03-15T15:00:00+00:00","start":"2024-03-14T15:00:00+00:00"},"task_id":"019011e6-e530-3aca-6cf7-2973387c255d","task_revisions":[{"data":{"2024-03-14T15:00:00":{"avg_llm_call_timing":2.45,"total_task_runs":150}},"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1"}],"total_task_runs":{"2024-03-14T15:00:00":150,"2024-03-14T16:00:00":165}}},"TaskRunTokenReport":{"properties":{"task_id":{"type":"string","format":"uuid","title":"Task ID","description":"Unique identifier of the task","examples":["0190a234-8dc6-6d08-aea9-928fcecad8f1"]},"date_range":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":"object","title":"Date Range","description":"Time period covered by the report, with start and end timestamps","examples":[{"end":"2024-01-31T23:59:59Z","start":"2024-01-01T00:00:00Z"}]},"total_input_tokens":{"type":"integer","minimum":0.0,"title":"Total Input Tokens","description":"Total number of input tokens consumed across all revisions and runs","examples":[10000]},"total_output_tokens":{"type":"integer","minimum":0.0,"title":"Total Output Tokens","description":"Total number of output tokens generated across all revisions and runs","examples":[5000]},"total_tokens":{"type":"integer","minimum":0.0,"title":"Total Tokens","description":"Combined total of input and output tokens across all revisions","examples":[15000]},"total_task_runs":{"type":"integer","minimum":0.0,"title":"Total Task Runs","description":"Total number of task executions across all revisions","examples":[100]},"task_revisions":{"items":{"$ref":"#/components/schemas/TaskRunRevisionTokenReport"},"type":"array","title":"Task Revisions","description":"Token usage breakdown by task revision, showing detailed statistics for each active revision"}},"type":"object","required":["task_id","date_range","total_input_tokens","total_output_tokens","total_tokens","total_task_runs","task_revisions"],"title":"TaskRunTokenReport","description":"Comprehensive token usage report for a task.\n\nThis model provides a detailed breakdown of token consumption across all revisions\nof a task, including aggregated totals and per-revision statistics.","example":{"date_range":{"end":"2024-01-31T23:59:59Z","start":"2024-01-01T00:00:00Z"},"task_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1","task_revisions":[{"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f2","total_input_tokens":6000,"total_output_tokens":3000,"total_task_runs":60,"total_tokens":9000},{"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f3","total_input_tokens":4000,"total_output_tokens":2000,"total_task_runs":40,"total_tokens":6000}],"total_input_tokens":10000,"total_output_tokens":5000,"total_task_runs":100,"total_tokens":15000}},"TaskRunUsageReport":{"properties":{"task_id":{"type":"string","format":"uuid","title":"Task Id","description":"The unique identifier of the Task.","examples":["019011e6-e530-3aca-6cf7-2973387c255d"]},"date_range":{"additionalProperties":true,"type":"object","title":"Date Range","description":"The time range for the report, with start and end timestamps.","examples":[{"end":"2024-03-15T15:00:00+00:00","start":"2024-03-14T15:00:00+00:00"}]},"aggregation":{"type":"string","enum":["day","week"],"title":"Aggregation","description":"The time interval for data aggregation. 'day' shows last 24 hours in hourly blocks, 'week' shows last 7 days in daily blocks.","examples":["day","week"]},"status":{"$ref":"#/components/schemas/UsageReportStatus","description":"Run outcome filter applied to this usage report.","examples":["ALL"]},"task_revisions":{"items":{"$ref":"#/components/schemas/TaskRunRevisionUsageReport"},"type":"array","title":"Task Revisions","description":"Usage data broken down by task revision, showing invocation counts for each active revision."},"total_counts":{"additionalProperties":{"type":"integer"},"type":"object","title":"Total Counts","description":"Total number of task invocations for each time interval across all revisions.","examples":[{"2024-03-14T15:00:00":150,"2024-03-14T16:00:00":165}]}},"type":"object","required":["task_id","date_range","aggregation","status","task_revisions","total_counts"],"title":"TaskRunUsageReport","example":{"aggregation":"day","date_range":{"end":"2024-03-15T15:00:00+00:00","start":"2024-03-14T15:00:00+00:00"},"task_id":"019011e6-e530-3aca-6cf7-2973387c255d","task_revisions":[{"data":{"2024-03-14T15:00:00":150,"2024-03-14T16:00:00":165},"task_revision_id":"0190a234-8dc6-6d08-aea9-928fcecad8f1"}],"total_counts":{"2024-03-14T15:00:00":150,"2024-03-14T16:00:00":165}}},"TaskShare":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"id":{"type":"string","format":"uuid","title":"Id"},"task_id":{"type":"string","format":"uuid","title":"Task Id"},"task_revision_id":{"type":"string","format":"uuid","title":"Task Revision Id"},"user_id":{"type":"string","format":"uuid","title":"User Id"},"task_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Run Id","description":"Optional TaskRun ID included as an example of the task's performance."},"task_name":{"type":"string","title":"Task Name","description":"Name of the associated task"},"short_id":{"type":"string","title":"Short Id"},"share_url":{"type":"string","title":"Share Url"},"views_count":{"type":"integer","title":"Views Count"},"active":{"type":"boolean","title":"Active"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"},"tags":{"items":{"$ref":"#/components/schemas/Tag"},"type":"array","title":"Tags","default":[]}},"type":"object","required":["id","task_id","task_revision_id","user_id","task_name","short_id","share_url","views_count","active","created","modified"],"title":"TaskShare","description":"Schema for task share response data"},"TaskShareCreate":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"},"task_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Revision Id"},"task_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Run Id","description":"Optional TaskRun ID to include as an example. Must belong to the task revision being shared."},"custom_short_id":{"anyOf":[{"type":"string","maxLength":5,"minLength":3,"pattern":"^[a-zA-Z0-9]+$"},{"type":"null"}],"title":"Custom Short Id"}},"type":"object","title":"TaskShareCreate","description":"Schema for creating a new task share"},"TaskToolChoiceEnum":{"type":"string","enum":["required","auto"],"title":"TaskToolChoiceEnum"},"TaskToolInvocationRead":{"properties":{"task_id":{"type":"string","title":"Task Id","description":"Task ID as a UUID string."},"task_revision_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Revision Id","description":"TaskRevision ID used for this invocation."},"task_name":{"type":"string","title":"Task Name"},"task_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Run Id"},"is_error":{"type":"boolean","title":"Is Error","default":false},"is_formatter":{"type":"boolean","title":"Is Formatter","default":false},"duration_ms":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Duration Ms","description":"Task tool execution duration in milliseconds."},"error_message":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Error Message","description":"Short error summary for failed task tool invocations."}},"type":"object","required":["task_id","task_name"],"title":"TaskToolInvocationRead","description":"Schema for an individual task tool invocation during a run."},"TaskToolResultType":{"type":"string","enum":["task","mcp","generic"],"title":"TaskToolResultType","description":"Type of tool result surfaced in task-agent events."},"TaskUpdate":{"properties":{"system_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"System Prompt","description":"The system prompt that is used to set the LLM context."},"user_prompt":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Prompt","description":"The description of the Task. It is not required to mention the outputs in the prompt, but it can help the model to understand the context better. Any input strings should be referenced with the dynamic `{...}` syntax, this informs the model to look for those values in the input data."},"llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Llm Model Id","description":"The LLM model to use for the Task."},"llm_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Llm Config","description":"Specific configuration parameters for the LLM model."},"output_format":{"anyOf":[{"additionalProperties":{"anyOf":[{"$ref":"#/components/schemas/TagOutputFormat-Input"},{"type":"string","enum":["str","string","boolean","bool","int","integer","list","object","number"]}]},"type":"object"},{"type":"null"}],"title":"Output Format","description":"This gives control over the structure of how the Task responds. Supports shorthand notation or an object with `type` can be specified for each attribute. In most instances, the LLM will be able to generate the desired output into the relevant property, but an optional `description` can be passed to provide it with additional context."},"task_forwarder_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Forwarder Id","description":"The unique identifier for a valid Task Forwarder. It is used to forward the Task output to another system or service."},"rag":{"anyOf":[{"$ref":"#/components/schemas/TaskRAG"},{"type":"null"}],"description":"**Note: This is a Paid Tier feature.** Provide additional domain specific input to the LLM so that it is able to reference user specific information when executing the Task. Examples of this could be a product catalogue, terms and conditions or a user manual."},"file_input_mode":{"anyOf":[{"$ref":"#/components/schemas/FileInputMode"},{"type":"null"}],"description":"Specifies what file types are accepted for visual LLM processing. Values: 'none' (default), 'image', 'pdf', 'image_or_pdf', 'any'."},"annotation":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Annotation"},"test":{"type":"boolean","title":"Test","description":"True if revision is a test revision. Test revisions cannot be live and are used for rapid Task testing/iteration.","default":false},"input_processors":{"items":{"$ref":"#/components/schemas/TaskInputProcessor"},"type":"array","title":"Input Processors","default":[]},"optimise_images":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Optimise Images","description":"When `true` (default) images will be automatically optimised before processing. Set to `false` to disable lossy image optimisation.","default":true},"fallback_llm_model_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Fallback Llm Model Id","description":"The LLM model to use as fallback if the primary model fails."},"fallback_llm_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Fallback Llm Config","description":"Specific configuration parameters for the fallback LLM model."},"tool_choice":{"anyOf":[{"$ref":"#/components/schemas/TaskToolChoiceEnum"},{"type":"null"}],"description":"Tool invocation mode when runtime tools are attached."},"task_mcp_tool_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Task Mcp Tool Ids","description":"Task MCP tool IDs attached to this revision."},"integration_tool_ids":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Integration Tool Ids","description":"Integration tool IDs attached to this revision.","deprecated":true},"integration_bindings":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskIntegrationBindingInput"},"type":"array"},{"type":"null"}],"title":"Integration Bindings"},"name":{"anyOf":[{"type":"string","maxLength":63,"pattern":"^[a-zA-Z0-9\\- ]+$"},{"type":"null"}],"title":"Name","description":"A name or reference for the Task."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"A longer description of the Task for internal reference."},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled","description":"When `true` the Task is active and callable. `false` denotes the Task is not yet operational."},"exposed_to_agents":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Exposed To Agents","description":"When `true` the Task is accessible to agents through the unauthenticated agent endpoint."},"task_run_visibility":{"anyOf":[{"type":"string","enum":["owner_only","editors_and_owners","all_viewers"]},{"type":"null"}],"title":"Task Run Visibility","description":"Controls who can view all task runs. 'owner_only' - only task owners see all runs (default), 'editors_and_owners' - task editors and owners see all runs, 'all_viewers' - all users with view permission see all runs."},"active_revisions":{"anyOf":[{"items":{"$ref":"#/components/schemas/TaskActiveRevision"},"type":"array"},{"type":"null"}],"title":"Active Revisions","description":"The revision currently active for this Task."},"tags":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Tags"},"revision_tags":{"anyOf":[{"items":{"type":"string","format":"uuid"},"type":"array"},{"type":"null"}],"title":"Revision Tags"}},"type":"object","title":"TaskUpdate"},"Task_AgentIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of task_agent roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of task_agent roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"Task AgentIAMMemberRoleUpdate"},"Task_AgentIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","edit","remove_editor","remove_member","remove_owner","run","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the task_agent."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"Task AgentIAMPermissionTest"},"Task_ForwarderIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of task_forwarder roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of task_forwarder roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"Task ForwarderIAMMemberRoleUpdate"},"Task_ForwarderIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","edit","remove_editor","remove_member","remove_owner","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the task_forwarder."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"Task ForwarderIAMPermissionTest"},"Task_Mcp_ServerIAMMemberRoleUpdate":{"properties":{"add":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Add","description":"A list of task_mcp_server roles to grant to the member.\n\nRoles in this list are applied to the member AFTER any removals specified in `remove`.\n\nThis may be combined with `remove_all` to replace the member's entire role list."},"remove":{"items":{"type":"string","enum":["editor","owner","viewer"]},"type":"array","title":"Remove","description":"A list of task_mcp_server roles to revoke from the member."},"remove_all":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Remove All","description":"Removes all existing roles from the member. This may be combined with `add` to replace all existing roles that the member holds.","default":false}},"type":"object","title":"Task Mcp ServerIAMMemberRoleUpdate"},"Task_Mcp_ServerIAMPermissionTest":{"properties":{"permissions":{"items":{"type":"string","enum":["add_editor","add_member","add_owner","edit","remove_editor","remove_member","remove_owner","view","view_members"]},"type":"array","title":"Permissions","description":"A list of permissions to test on the task_mcp_server."},"member":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Member"}},"type":"object","required":["permissions"],"title":"Task Mcp ServerIAMPermissionTest"},"TeamsInstallationRead":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"project_integration_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Project Integration Id"},"tenant_id":{"type":"string","title":"Tenant Id"},"team_id":{"type":"string","title":"Team Id"},"team_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Team Name"},"status":{"$ref":"#/components/schemas/TeamsInstallationStatus"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"type":"object","required":["id","tenant_id","team_id","status","created","modified"],"title":"TeamsInstallationRead"},"TeamsInstallationStatus":{"type":"string","enum":["pending_link","active","revoked","disconnected"],"title":"TeamsInstallationStatus"},"TeamsInstallationsResponse":{"properties":{"auth_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth State"},"auth_state_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth State Reason"},"installations":{"items":{"$ref":"#/components/schemas/TeamsInstallationRead"},"type":"array","title":"Installations"}},"type":"object","title":"TeamsInstallationsResponse"},"TeamsLinkedInstallationRead":{"properties":{"teams_installation_id":{"type":"string","format":"uuid","title":"Teams Installation Id"},"tenant_id":{"type":"string","title":"Tenant Id"},"team_id":{"type":"string","title":"Team Id"},"team_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Team Name"},"status":{"$ref":"#/components/schemas/TeamsInstallationStatus"},"created":{"type":"string","title":"Created"},"modified":{"type":"string","title":"Modified"}},"type":"object","required":["teams_installation_id","tenant_id","team_id","status","created","modified"],"title":"TeamsLinkedInstallationRead"},"TeamsSetupResponse":{"properties":{"teams_install_url":{"type":"string","title":"Teams Install Url"},"auth_state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth State"},"auth_state_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth State Reason"},"linked_installations":{"items":{"$ref":"#/components/schemas/TeamsInstallationRead"},"type":"array","title":"Linked Installations"}},"type":"object","required":["teams_install_url"],"title":"TeamsSetupResponse"},"TeamsTabLinkRequest":{"properties":{"teams_sso_token":{"type":"string","minLength":1,"title":"Teams Sso Token"},"tenant_id":{"type":"string","maxLength":64,"title":"Tenant Id"},"team_id":{"type":"string","maxLength":255,"title":"Team Id"},"team_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Team Name"},"channel_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Channel Id"},"channel_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Channel Name"},"content_url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"title":"Content Url"}},"type":"object","required":["teams_sso_token","tenant_id","team_id"],"title":"TeamsTabLinkRequest"},"TeamsTabLinkResponse":{"properties":{"auth_state":{"type":"string","title":"Auth State"},"auth_state_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth State Reason"},"installation":{"$ref":"#/components/schemas/TeamsLinkedInstallationRead"}},"type":"object","required":["auth_state","installation"],"title":"TeamsTabLinkResponse"},"ToolCallInfo":{"properties":{"name":{"type":"string","title":"Name","description":"Name of the tool/task tool called."},"args":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Args","description":"Arguments passed to the tool."}},"type":"object","required":["name"],"title":"ToolCallInfo","description":"Information about a tool/task tool call within an event."},"ToolResultInfo":{"properties":{"name":{"type":"string","title":"Name","description":"Name of the tool/task tool."},"tool_result_type":{"$ref":"#/components/schemas/TaskToolResultType","description":"Result source type: 'task' for TaskTool results, otherwise 'generic'.","default":"generic"},"task_run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Task Run Id","description":"TaskRun ID when the result originated from a task tool."},"mcp_server_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mcp Server Name","description":"MCP server name when the result originated from an MCP tool."},"is_formatter_output":{"type":"boolean","title":"Is Formatter Output","description":"True when this result is from the output formatter task tool.","default":false},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result","description":"Result returned by the tool."}},"type":"object","required":["name"],"title":"ToolResultInfo","description":"Information about a tool/task tool result within an event."},"TriggerEventStatus":{"type":"string","enum":["received","processing","approval_required","completed","failed","duplicate","skipped"],"title":"TriggerEventStatus"},"TriggerStatus":{"type":"string","enum":["draft","disabled","enabled"],"title":"TriggerStatus","description":"Lifecycle status for triggers."},"TriggerTargetType":{"type":"string","enum":["task","task_agent"],"title":"TriggerTargetType","description":"Target resource type for trigger execution."},"TriggerType":{"type":"string","enum":["webhook","schedule","gmail_inbox"],"title":"TriggerType","description":"Supported trigger types."},"UsageReportStatus":{"type":"string","enum":["ALL","SUCCESS","FAIL"],"title":"UsageReportStatus","description":"Status filter for usage-report endpoints."},"User":{"properties":{"email":{"type":"string","format":"email","title":"Email"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"bio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bio"},"avatar_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar Url"},"subscribed_to_newsletter":{"type":"boolean","title":"Subscribed To Newsletter","default":false},"job_role":{"anyOf":[{"type":"string","enum":["student","engineer","designer","product manager","entrepreneur","marketer","educator","researcher","freelancer","other"]},{"type":"null"}],"title":"Job Role"},"id":{"type":"string","format":"uuid","title":"Id"},"is_onboarding":{"type":"boolean","title":"Is Onboarding"}},"type":"object","required":["email","name","id","is_onboarding"],"title":"User"},"UserOAuthClientCreate":{"properties":{"name":{"type":"string","title":"Name","description":"Name for the new OAuth client.","examples":["Production API Client"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Optional description of the client's purpose.","examples":["OAuth client for production API access"]},"redirect_uris":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Redirect Uris","description":"List of authorized redirect URIs.\nRequired if using authorization_code or implicit grant types.","examples":[["https://app.example.com/oauth/callback"]]},"grant_types":{"anyOf":[{"items":{"$ref":"#/components/schemas/OAuthClientGrantType"},"type":"array"},{"type":"null"}],"title":"Grant Types","description":"List of OAuth grant types to enable.","examples":[["client_credentials","refresh_token"]]},"type":{"type":"string","enum":["user","project"],"title":"Type","description":"Type of OAuth client to create:\n- user: Standard client tied to creating user's permissions\n- project: Service account client with project-level permissions","default":"user","examples":["user","project"]},"token_endpoint_auth_method":{"type":"string","enum":["client_secret_basic","client_secret_post","none"],"title":"Token Endpoint Auth Method","description":"Authentication method for the client:\n- client_secret_basic: Client ID and secret sent in HTTP headers\n- client_secret_post: Client ID and secret sent in request body\n- none: No client authentication (required for public clients using PKCE)","default":"client_secret_basic","examples":["client_secret_basic","client_secret_post","none"]},"pkce_required":{"type":"boolean","title":"Pkce Required","description":"Whether to require PKCE (Proof Key for Code Exchange) for authorization code flows.\nPKCE enhances security by requiring code_challenge and code_verifier parameters.\nIMPORTANT: Only applicable when 'authorization_code' is included in grant_types.\nStrongly recommended for public clients (mobile apps, SPAs) and beneficial for all clients.","default":false,"examples":[true,false]},"pkce_challenge_method":{"$ref":"#/components/schemas/OAuthClientPKCEChallengeMethod","description":"PKCE code challenge method when PKCE is enabled.\n- S256: SHA256 hash of code verifier (recommended and secure)\n- plain: Plain text code verifier (not recommended, only for testing)","default":"S256","examples":["S256"]}},"type":"object","required":["name"],"title":"UserOAuthClientCreate"},"UserProfileUpdate":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"bio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bio"},"subscribed_to_newsletter":{"type":"boolean","title":"Subscribed To Newsletter","default":false},"job_role":{"anyOf":[{"type":"string","enum":["student","engineer","designer","product manager","entrepreneur","marketer","educator","researcher","freelancer","other"]},{"type":"null"}],"title":"Job Role"}},"type":"object","title":"UserProfileUpdate"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VisionFilter":{"type":"string","enum":["image","pdf"],"title":"VisionFilter","description":"Vision (input) capability filter for model listing."},"WebhookAuthMethod":{"type":"string","enum":["hmac_sha256","bearer_token"],"title":"WebhookAuthMethod","description":"Authentication methods for webhook triggers."},"WebhookForwarderCreate":{"properties":{"name":{"type":"string","title":"Name","description":"A descriptive name for the Task Forwarder."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional details about the Task Forwarder's purpose or configuration."},"forwarder_type":{"type":"string","const":"webhook","title":"Forwarder Type","description":"Type of forwarder: webhook for HTTP POST delivery","default":"webhook"},"config":{"$ref":"#/components/schemas/TaskForwarderConfig","description":"Configuration parameters for the Task Forwarder such as a `destination` URL."},"config_sensitive":{"anyOf":[{"$ref":"#/components/schemas/TaskForwarderSensitiveConfig"},{"type":"null"}],"description":"Sensitive parameters for the Task Forwarder such as a `signing_key`."}},"type":"object","required":["name","config"],"title":"WebhookForwarderCreate"},"WebhookForwarderInDB":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"The unique identifier of the Task Forwarder."},"project_id":{"type":"string","format":"uuid","title":"Project Id","description":"The Project that the Task Forwarder belongs to."},"created":{"type":"string","title":"Created","description":"When the Task Forwarder was created."},"modified":{"type":"string","title":"Modified","description":"When the Task Forwarder was last updated."},"name":{"type":"string","title":"Name","description":"A descriptive name for the Task Forwarder."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional details about the Task Forwarder's purpose or configuration."},"forwarder_type":{"type":"string","const":"webhook","title":"Forwarder Type","description":"Type of forwarder: webhook for HTTP POST delivery","default":"webhook"},"config":{"$ref":"#/components/schemas/TaskForwarderConfig","description":"Configuration parameters for the Task Forwarder such as a `destination` URL."},"config_sensitive":{"anyOf":[{"$ref":"#/components/schemas/TaskForwarderSensitiveConfig"},{"type":"null"}],"description":"Sensitive parameters for the Task Forwarder such as a `signing_key`."}},"type":"object","required":["id","project_id","created","modified","name","config"],"title":"WebhookForwarderInDB"},"WebhookForwarderUpdate":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"A descriptive name for the Task Forwarder."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional details about the Task Forwarder's purpose or configuration."},"forwarder_type":{"type":"string","const":"webhook","title":"Forwarder Type","description":"Type of forwarder: webhook","default":"webhook"},"config":{"anyOf":[{"$ref":"#/components/schemas/TaskForwarderConfig"},{"type":"null"}],"description":"Configuration parameters for the Task Forwarder such as a `destination` URL."},"config_sensitive":{"anyOf":[{"$ref":"#/components/schemas/TaskForwarderSensitiveConfig"},{"type":"null"}],"description":"Sensitive parameters for the Task Forwarder such as a `signing_key`."}},"type":"object","title":"WebhookForwarderUpdate"},"WebhookTriggerCreate":{"properties":{"name":{"type":"string","maxLength":63,"minLength":1,"title":"Name","description":"A descriptive name for the trigger."},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Description","description":"Additional details about the trigger's purpose."},"status":{"$ref":"#/components/schemas/TriggerStatus","description":"Lifecycle status for the trigger (draft, disabled, enabled).","default":"enabled"},"auth_method":{"type":"string","enum":["hmac_sha256","bearer_token"],"title":"Auth Method","description":"Authentication method for incoming webhooks."},"auth_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Auth Config","description":"Authentication configuration (e.g., signature header name)."},"auth_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Secret","description":"Secret key for authentication (only shown on creation)."},"payload_mapping":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Mapping","description":"JSONPath mappings from webhook payload to Task inputs."},"include_raw_payload":{"type":"boolean","title":"Include Raw Payload","description":"Whether to include the entire payload as _raw_payload.","default":false},"idempotency_key_path":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Idempotency Key Path","description":"JSONPath to extract idempotency key from payload."},"idempotency_ttl_seconds":{"type":"integer","maximum":604800.0,"minimum":60.0,"title":"Idempotency Ttl Seconds","description":"How long to remember processed idempotency keys.","default":86400},"target_type":{"$ref":"#/components/schemas/TriggerTargetType","description":"The target resource type for this trigger."},"target_id":{"type":"string","format":"uuid","title":"Target Id","description":"The target resource ID for this trigger."},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id","description":"Optional pinned TaskAgent revision for TaskAgent triggers."}},"type":"object","required":["name","auth_method","target_type","target_id"],"title":"WebhookTriggerCreate","description":"Schema for creating a new webhook trigger."},"WebhookTriggerEventDetailResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the event."},"webhook_trigger_id":{"type":"string","format":"uuid","title":"Webhook Trigger Id","description":"The trigger this event belongs to."},"request_id":{"type":"string","title":"Request Id","description":"Request ID for tracing."},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key","description":"Idempotency key if extracted."},"http_method":{"type":"string","title":"Http Method","description":"HTTP method of the request."},"source_ip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Ip","description":"Source IP address of the request."},"status":{"type":"string","title":"Status","description":"Event status (received, processing, completed, failed, duplicate, skipped)."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error message if failed."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Error code if failed."},"task_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Run Id","description":"Associated TaskRun ID if successful."},"task_agent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Run Id","description":"Associated TaskAgentRun ID if successful."},"received_at":{"type":"string","title":"Received At","description":"When the webhook was received."},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At","description":"When processing completed."},"response_status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Status Code","description":"HTTP response status code."},"response_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Time Ms","description":"Response time in milliseconds."},"task_agent_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Id","description":"The TaskAgent ID for agent-targeted triggers."},"request_data":{"$ref":"#/components/schemas/WebhookTriggerEventRequestData","description":"Captured and transformed request data."}},"type":"object","required":["id","webhook_trigger_id","request_id","http_method","status","received_at","request_data"],"title":"WebhookTriggerEventDetailResponse","description":"Detailed response schema for a webhook trigger event."},"WebhookTriggerEventRequestData":{"properties":{"request_headers":{"additionalProperties":true,"type":"object","title":"Request Headers","description":"Captured request headers."},"request_body":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"string"},{"type":"null"}],"title":"Request Body","description":"Request body parsed as JSON object when possible."},"mapped_input":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Mapped Input","description":"Mapped input sent to execution."}},"type":"object","required":["request_headers"],"title":"WebhookTriggerEventRequestData","description":"Request payload details for a webhook trigger event."},"WebhookTriggerEventResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the event."},"webhook_trigger_id":{"type":"string","format":"uuid","title":"Webhook Trigger Id","description":"The trigger this event belongs to."},"request_id":{"type":"string","title":"Request Id","description":"Request ID for tracing."},"idempotency_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key","description":"Idempotency key if extracted."},"http_method":{"type":"string","title":"Http Method","description":"HTTP method of the request."},"source_ip":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Ip","description":"Source IP address of the request."},"status":{"type":"string","title":"Status","description":"Event status (received, processing, completed, failed, duplicate, skipped)."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"Error message if failed."},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code","description":"Error code if failed."},"task_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Run Id","description":"Associated TaskRun ID if successful."},"task_agent_run_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Run Id","description":"Associated TaskAgentRun ID if successful."},"received_at":{"type":"string","title":"Received At","description":"When the webhook was received."},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At","description":"When processing completed."},"response_status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Status Code","description":"HTTP response status code."},"response_time_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Time Ms","description":"Response time in milliseconds."}},"type":"object","required":["id","webhook_trigger_id","request_id","http_method","status","received_at"],"title":"WebhookTriggerEventResponse","description":"Response schema for a webhook trigger event."},"WebhookTriggerListItem":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the trigger."},"target_type":{"$ref":"#/components/schemas/TriggerTargetType","description":"The target resource type for this trigger."},"target_id":{"type":"string","format":"uuid","title":"Target Id","description":"The target resource ID for this trigger."},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id","description":"Optional pinned TaskAgent revision for TaskAgent triggers."},"trigger_type":{"type":"string","const":"webhook","title":"Trigger Type","description":"The type of trigger (webhook for this endpoint).","default":"webhook"},"name":{"type":"string","title":"Name","description":"A descriptive name for the trigger."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional details about the trigger's purpose."},"status":{"$ref":"#/components/schemas/TriggerStatus","description":"Lifecycle status for the trigger (draft, disabled, enabled)."},"created":{"type":"string","title":"Created","description":"When the trigger was created."},"auth_method":{"$ref":"#/components/schemas/WebhookAuthMethod","description":"Authentication method for incoming webhooks."}},"type":"object","required":["id","target_type","target_id","name","status","created","auth_method"],"title":"WebhookTriggerListItem","description":"List item for webhook triggers."},"WebhookTriggerResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the trigger."},"target_type":{"$ref":"#/components/schemas/TriggerTargetType","description":"The target resource type for this trigger."},"target_id":{"type":"string","format":"uuid","title":"Target Id","description":"The target resource ID for this trigger."},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id","description":"Optional pinned TaskAgent revision for TaskAgent triggers."},"trigger_type":{"type":"string","const":"webhook","title":"Trigger Type","description":"The type of trigger (webhook for this endpoint).","default":"webhook"},"name":{"type":"string","title":"Name","description":"A descriptive name for the trigger."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional details about the trigger's purpose."},"status":{"$ref":"#/components/schemas/TriggerStatus","description":"Lifecycle status for the trigger (draft, disabled, enabled)."},"endpoint_id":{"type":"string","title":"Endpoint Id","description":"Unique endpoint identifier used in the webhook URL."},"endpoint_url":{"type":"string","title":"Endpoint Url","description":"Full URL for receiving webhook requests."},"auth_method":{"type":"string","title":"Auth Method","description":"Authentication method for incoming webhooks."},"auth_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Auth Config","description":"Authentication configuration (e.g., signature header name)."},"payload_mapping":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Mapping","description":"JSONPath mappings from webhook payload to Task inputs."},"include_raw_payload":{"type":"boolean","title":"Include Raw Payload","description":"Whether to include the entire payload as _raw_payload."},"idempotency_key_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key Path","description":"JSONPath to extract idempotency key from payload."},"idempotency_ttl_seconds":{"type":"integer","title":"Idempotency Ttl Seconds","description":"How long to remember processed idempotency keys."},"created":{"type":"string","title":"Created","description":"When the trigger was created."},"modified":{"type":"string","title":"Modified","description":"When the trigger was last updated."},"created_by_user_id":{"type":"string","format":"uuid","title":"Created By User Id","description":"User who created the trigger."}},"type":"object","required":["id","target_type","target_id","name","status","endpoint_id","endpoint_url","auth_method","include_raw_payload","idempotency_ttl_seconds","created","modified","created_by_user_id"],"title":"WebhookTriggerResponse","description":"Response schema for a webhook trigger."},"WebhookTriggerUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":63,"minLength":1},{"type":"null"}],"title":"Name","description":"A descriptive name for the trigger."},"description":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Description","description":"Additional details about the trigger's purpose."},"status":{"anyOf":[{"$ref":"#/components/schemas/TriggerStatus"},{"type":"null"}],"description":"Lifecycle status for the trigger (draft, disabled, enabled)."},"auth_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Auth Config","description":"Authentication configuration (e.g., signature header name)."},"auth_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Secret","description":"Secret key for authentication (only shown on creation)."},"payload_mapping":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Mapping","description":"JSONPath mappings from webhook payload to Task inputs."},"include_raw_payload":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Include Raw Payload","description":"Whether to include the entire payload as _raw_payload."},"idempotency_key_path":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Idempotency Key Path","description":"JSONPath to extract idempotency key from payload."},"idempotency_ttl_seconds":{"anyOf":[{"type":"integer","maximum":604800.0,"minimum":60.0},{"type":"null"}],"title":"Idempotency Ttl Seconds","description":"How long to remember processed idempotency keys."},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id","description":"Optional pinned TaskAgent revision for TaskAgent triggers."}},"type":"object","title":"WebhookTriggerUpdate","description":"Schema for updating a webhook trigger."},"WebhookTriggerWithSecret":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique identifier for the trigger."},"target_type":{"$ref":"#/components/schemas/TriggerTargetType","description":"The target resource type for this trigger."},"target_id":{"type":"string","format":"uuid","title":"Target Id","description":"The target resource ID for this trigger."},"task_agent_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Task Agent Revision Id","description":"Optional pinned TaskAgent revision for TaskAgent triggers."},"trigger_type":{"type":"string","const":"webhook","title":"Trigger Type","description":"The type of trigger (webhook for this endpoint).","default":"webhook"},"name":{"type":"string","title":"Name","description":"A descriptive name for the trigger."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Additional details about the trigger's purpose."},"status":{"$ref":"#/components/schemas/TriggerStatus","description":"Lifecycle status for the trigger (draft, disabled, enabled)."},"endpoint_id":{"type":"string","title":"Endpoint Id","description":"Unique endpoint identifier used in the webhook URL."},"endpoint_url":{"type":"string","title":"Endpoint Url","description":"Full URL for receiving webhook requests."},"auth_method":{"type":"string","title":"Auth Method","description":"Authentication method for incoming webhooks."},"auth_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Auth Config","description":"Authentication configuration (e.g., signature header name)."},"payload_mapping":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Payload Mapping","description":"JSONPath mappings from webhook payload to Task inputs."},"include_raw_payload":{"type":"boolean","title":"Include Raw Payload","description":"Whether to include the entire payload as _raw_payload."},"idempotency_key_path":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency Key Path","description":"JSONPath to extract idempotency key from payload."},"idempotency_ttl_seconds":{"type":"integer","title":"Idempotency Ttl Seconds","description":"How long to remember processed idempotency keys."},"created":{"type":"string","title":"Created","description":"When the trigger was created."},"modified":{"type":"string","title":"Modified","description":"When the trigger was last updated."},"created_by_user_id":{"type":"string","format":"uuid","title":"Created By User Id","description":"User who created the trigger."},"auth_secret":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Secret","description":"The authentication secret (only shown once on creation or rotation)."}},"type":"object","required":["id","target_type","target_id","name","status","endpoint_id","endpoint_url","auth_method","include_raw_payload","idempotency_ttl_seconds","created","modified","created_by_user_id"],"title":"WebhookTriggerWithSecret","description":"Response schema for webhook trigger creation (includes secret)."},"WhoAmIClientDetails":{"properties":{"org_id":{"type":"string","format":"uuid","title":"Org Id"},"project_id":{"type":"string","format":"uuid","title":"Project Id"}},"type":"object","required":["org_id","project_id"],"title":"WhoAmIClientDetails","description":"OAuth client details when authenticated via OAuth."},"WhoAmIResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"email":{"type":"string","format":"email","title":"Email"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"client":{"anyOf":[{"$ref":"#/components/schemas/WhoAmIClientDetails"},{"type":"null"}]}},"type":"object","required":["id","email","name"],"title":"WhoAmIResponse","description":"Response model for the whoami endpoint."},"_TaskAgentEvalCaseReference":{"properties":{"case_order":{"type":"integer","title":"Case Order"},"reference_source_run_id":{"type":"string","format":"uuid","title":"Reference Source Run Id"}},"type":"object","required":["case_order","reference_source_run_id"],"title":"_TaskAgentEvalCaseReference"},"ErrorResponse":{"type":"object","description":"Envelope for errors raised through the application's exception handlers: `{\"detail\": <value>}`. See the `detail` property for the shapes `<value>` can take. An unhandled server error is the one exception and returns plain text.","properties":{"detail":{"description":"A plain error message, a list of field-level validation errors, a service validation error, or a domain error object with `reason` and `message`.","oneOf":[{"type":"string","description":"Simple error message","example":"Not authenticated"},{"type":"array","description":"Field-level validation errors","items":{"type":"object","properties":{"loc":{"type":"array","items":{"type":["string","integer"]},"description":"Path to the error location. Integer segments index into a list."},"msg":{"type":"string","description":"Human-readable error message. Present on errors produced by FastAPI's own request validation."},"message":{"type":"string","description":"Human-readable error message. Used instead of `msg` by Rightbrain's own validators."},"type":{"type":"string","description":"Error type identifier"}},"required":["type"]},"example":[{"loc":["body","llm_model_id"],"msg":"Input should be a valid UUID","type":"uuid_parsing"}]},{"type":"object","description":"Validation error returned by a service after request parsing, such as a Task clone dependency failure.","properties":{"type":{"type":"string","const":"validation_error"},"errors":{"type":"array","items":{"type":"object","properties":{"loc":{"type":"array","items":{"type":["string","integer"]},"description":"Path to the error location. Integer segments index into a list."},"msg":{"type":"string","description":"Human-readable error message. Present on errors produced by FastAPI's own request validation."},"message":{"type":"string","description":"Human-readable error message. Used instead of `msg` by Rightbrain's own validators."},"type":{"type":"string","description":"Error type identifier"}},"required":["type"]}}},"required":["type","errors"]},{"type":"object","description":"Domain error raised via a brain.exc.BaseError subclass. The exact extra field name and shape vary by error type.","properties":{"reason":{"type":"string","description":"Machine-readable, upper-snake-case error reason, e.g. RESOURCE_NOT_FOUND, PERMISSION_CHECK_FAILED, TAG_NAME_CONFLICT."},"message":{"type":"string","description":"Human-readable error message"}},"required":["reason","message"],"additionalProperties":true,"example":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60]","resourceNotFoundError":{"field":"project","value":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60"}}},{"type":"object","description":"Integration precondition failure. Uses `code` rather than `reason`, and carries no extra field. Raised by the Gmail trigger routes when the underlying integration is not authorized.","properties":{"code":{"type":"string","description":"Machine-readable code, e.g. GMAIL_INTEGRATION_AUTH_REQUIRED."},"message":{"type":"string","description":"Human-readable error message"}},"required":["code","message"],"example":{"code":"GMAIL_INTEGRATION_AUTH_REQUIRED","message":"Authorize Gmail before creating a Gmail inbox trigger."}}],"example":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60]","resourceNotFoundError":{"field":"project","value":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60"}}}},"required":["detail"],"example":{"detail":{"reason":"RESOURCE_NOT_FOUND","message":"Could not find project [019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60]","resourceNotFoundError":{"field":"project","value":"019f8a00-1c3d-7e42-b8f1-2a5c9d4e7b60"}}}},"PaginationInfo":{"type":"object","description":"Pagination metadata for navigating large result sets","properties":{"has_next":{"type":"boolean","description":"Indicates if more results are available"},"next_cursor":{"type":["string","null"],"format":"uuid","description":"Cursor for fetching the next page"},"page_limit":{"type":"integer","description":"Maximum items per page","minimum":1,"maximum":100,"default":20},"total_count":{"type":["integer","null"],"description":"Total number of items (if available)"}},"required":["has_next","page_limit"]},"TaskSharePublicExampleRun":{"description":"Example task run data included on a public task share.","properties":{"run_data":{"description":"The request data submitted to the task.","title":"Run Data"},"response":{"description":"The task's response.","title":"Response"},"files":{"items":{"$ref":"#/components/schemas/TaskSharePublicExampleRunFile"},"title":"Files","type":"array"},"output_file":{"anyOf":[{"$ref":"#/components/schemas/TaskSharePublicExampleRunOutputFile"},{"type":"null"}],"default":null},"output_modality":{"title":"Output Modality","type":"string"},"input_tokens":{"title":"Input Tokens","type":"integer"},"output_tokens":{"title":"Output Tokens","type":"integer"},"total_tokens":{"title":"Total Tokens","type":"integer"},"llm_call_timing":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Llm Call Timing"},"mcp_tool_timing":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Mcp Tool Timing"},"input_processor_timing":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"title":"Input Processor Timing"},"charged_credits":{"title":"Charged Credits","type":"number"},"created":{"description":"ISO 8601 timestamp of the example run.","title":"Created","type":"string"}},"required":["run_data","response","output_modality","input_tokens","output_tokens","total_tokens","charged_credits","created"],"title":"TaskSharePublicExampleRun","type":"object"},"TaskSharePublicExampleRunFile":{"description":"A file attached to a public task share's example run.","properties":{"original_filename":{"title":"Original Filename","type":"string"},"stored_filename":{"title":"Stored Filename","type":"string"},"content_type":{"title":"Content Type","type":"string"},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Size Bytes"},"download_url":{"title":"Download Url","type":"string"}},"required":["original_filename","stored_filename","content_type","download_url"],"title":"TaskSharePublicExampleRunFile","type":"object"},"TaskSharePublicExampleRunOutputFile":{"description":"The generated output file for a public task share's example run.\n\nPresent only for image, audio, and pdf output modalities.","properties":{"filename":{"title":"Filename","type":"string"},"download_url":{"title":"Download Url","type":"string"},"type":{"title":"Type","type":"string"}},"required":["filename","download_url","type"],"title":"TaskSharePublicExampleRunOutputFile","type":"object"},"TaskSharePublic":{"description":"Public JSON view of a shared task.\n\nReturned by the public task-share endpoint when the caller sends\n`Accept: application/json` instead of requesting the HTML share page.","properties":{"name":{"title":"Name","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"system_prompt":{"title":"System Prompt","type":"string"},"user_prompt":{"title":"User Prompt","type":"string"},"output_format":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Output Format"},"output_modality":{"title":"Output Modality","type":"string"},"file_input_mode":{"default":"none","title":"File Input Mode","type":"string"},"input_processors":{"items":{"additionalProperties":true,"type":"object"},"title":"Input Processors","type":"array"},"optimise_images":{"title":"Optimise Images","type":"boolean"},"llm_model_id":{"title":"Llm Model Id","type":"string"},"llm_model_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Model name for cross-environment cloning, since model IDs differ per environment.","title":"Llm Model Name"},"llm_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Llm Config"},"example_run":{"anyOf":[{"$ref":"#/components/schemas/TaskSharePublicExampleRun"},{"type":"null"}],"default":null,"description":"Example run data, present only when the share includes one."}},"required":["name","system_prompt","user_prompt","output_modality","optimise_images","llm_model_id"],"title":"TaskSharePublic","type":"object"},"TaskAgentSharePublicAgent":{"description":"Public TaskAgent metadata.","properties":{"name":{"title":"Name","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"}},"required":["name"],"title":"TaskAgentSharePublicAgent","type":"object"},"TaskAgentSharePublicInputProcessor":{"description":"Public task input processor configuration for a shared TaskAgent.","properties":{"param_name":{"description":"Task input parameter processed before task execution.","title":"Param Name","type":"string"},"input_processor":{"description":"Input processor slug/type used for the parameter.","title":"Input Processor","type":"string"},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"Public operational configuration for this input processor. TaskAgent shares intentionally expose this config because it is material to how the shared task tool operates.","title":"Config"}},"required":["param_name","input_processor"],"title":"TaskAgentSharePublicInputProcessor","type":"object"},"TaskAgentSharePublicIntegration":{"description":"Public integration attachment with credentials redacted.","properties":{"type":{"title":"Type","type":"string"},"name":{"title":"Name","type":"string"},"enabled":{"title":"Enabled","type":"boolean"},"order":{"title":"Order","type":"integer"},"tools":{"items":{"$ref":"#/components/schemas/TaskAgentSharePublicTool"},"title":"Tools","type":"array"}},"required":["type","name","enabled","order"],"title":"TaskAgentSharePublicIntegration","type":"object"},"TaskAgentSharePublicMcpServer":{"description":"Public MCP server attachment with secret-bearing fields redacted.","properties":{"name":{"title":"Name","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"server_url":{"title":"Server Url","type":"string"},"canonical_resource":{"title":"Canonical Resource","type":"string"},"transport":{"title":"Transport","type":"string"},"enabled":{"title":"Enabled","type":"boolean"},"order":{"title":"Order","type":"integer"},"tools":{"items":{"$ref":"#/components/schemas/TaskAgentSharePublicTool"},"title":"Tools","type":"array"}},"required":["name","server_url","canonical_resource","transport","enabled","order"],"title":"TaskAgentSharePublicMcpServer","type":"object"},"TaskAgentSharePublicModel":{"description":"Public model hint for a shared TaskAgent revision.","properties":{"id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"default":null,"title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Name"},"alias":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Alias"},"provider":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Provider"},"vendor":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Vendor"}},"title":"TaskAgentSharePublicModel","type":"object"},"TaskAgentSharePublicRegisteredTool":{"description":"Public registered first-party tool attachment.","properties":{"key":{"title":"Key","type":"string"},"version":{"title":"Version","type":"string"},"enabled":{"title":"Enabled","type":"boolean"},"order":{"title":"Order","type":"integer"},"name":{"readOnly":true,"title":"Name","type":"string"},"tool_names":{"items":{"type":"string"},"readOnly":true,"title":"Tool Names","type":"array"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"readOnly":true,"title":"Description"}},"required":["key","version","enabled","order","name","tool_names","description"],"title":"TaskAgentSharePublicRegisteredTool","type":"object"},"TaskAgentSharePublicRevision":{"description":"Public allowlisted TaskAgent revision detail.","properties":{"instruction":{"title":"Instruction","type":"string"},"mode":{"$ref":"#/components/schemas/TaskAgentMode"},"llm_model":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentSharePublicModel"},{"type":"null"}],"default":null},"fallback_llm_model":{"anyOf":[{"$ref":"#/components/schemas/TaskAgentSharePublicModel"},{"type":"null"}],"default":null},"memory_strategy":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Memory Strategy"},"memory_config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Memory Config"},"max_turns":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"title":"Max Turns"},"task_tools":{"items":{"$ref":"#/components/schemas/TaskAgentSharePublicTaskTool"},"title":"Task Tools","type":"array"},"skills":{"items":{"$ref":"#/components/schemas/TaskAgentSharePublicSkill"},"title":"Skills","type":"array"},"mcp_servers":{"items":{"$ref":"#/components/schemas/TaskAgentSharePublicMcpServer"},"title":"Mcp Servers","type":"array"},"integrations":{"items":{"$ref":"#/components/schemas/TaskAgentSharePublicIntegration"},"title":"Integrations","type":"array"},"registered_tools":{"items":{"$ref":"#/components/schemas/TaskAgentSharePublicRegisteredTool"},"title":"Registered Tools","type":"array"}},"required":["instruction","mode"],"title":"TaskAgentSharePublicRevision","type":"object"},"TaskAgentSharePublicSkill":{"description":"Public skill attachment.","properties":{"slug":{"title":"Slug","type":"string"},"display_name":{"title":"Display Name","type":"string"},"enabled":{"title":"Enabled","type":"boolean"},"order":{"title":"Order","type":"integer"},"source":{"enum":["global","project"],"readOnly":true,"title":"Source","type":"string"}},"required":["slug","display_name","enabled","order","source"],"title":"TaskAgentSharePublicSkill","type":"object"},"TaskAgentSharePublicTaskRevision":{"description":"Public summary of a pinned task revision used as a task tool.","properties":{"system_prompt":{"title":"System Prompt","type":"string"},"user_prompt":{"title":"User Prompt","type":"string"},"output_format":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"title":"Output Format"},"output_modality":{"title":"Output Modality","type":"string"},"file_input_mode":{"default":"none","title":"File Input Mode","type":"string"},"input_processors":{"description":"Input processor configuration exposed on public TaskAgent shares. Processor config is public share material because it describes how task-tool inputs are transformed before execution.","items":{"$ref":"#/components/schemas/TaskAgentSharePublicInputProcessor"},"title":"Input Processors","type":"array"}},"required":["system_prompt","user_prompt","output_modality"],"title":"TaskAgentSharePublicTaskRevision","type":"object"},"TaskAgentSharePublicTaskTool":{"description":"Public task tool attachment.","properties":{"task_name":{"title":"Task Name","type":"string"},"task_description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Task Description"},"enabled":{"title":"Enabled","type":"boolean"},"order":{"title":"Order","type":"integer"},"is_output_formatter":{"title":"Is Output Formatter","type":"boolean"},"task_revision":{"$ref":"#/components/schemas/TaskAgentSharePublicTaskRevision"}},"required":["task_name","enabled","order","is_output_formatter","task_revision"],"title":"TaskAgentSharePublicTaskTool","type":"object"},"TaskAgentSharePublicTool":{"description":"Public tool metadata.","properties":{"name":{"title":"Name","type":"string"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"}},"required":["name"],"title":"TaskAgentSharePublicTool","type":"object"},"TaskAgentSharePublic":{"description":"Public response for a TaskAgent share.","properties":{"short_id":{"title":"Short Id","type":"string"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Description"},"views_count":{"title":"Views Count","type":"integer"},"created":{"title":"Created","type":"string"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"title":"Expires At"},"agent":{"$ref":"#/components/schemas/TaskAgentSharePublicAgent"},"revision":{"$ref":"#/components/schemas/TaskAgentSharePublicRevision"}},"required":["short_id","views_count","created","agent","revision"],"title":"TaskAgentSharePublic","type":"object"},"PaginatedResultSet":{"type":"object","description":"A paginated set of results with navigation information","properties":{"results":{"type":"array","description":"Array of items in the current page","items":{"type":"object"}},"pagination":{"$ref":"#/components/schemas/PaginationInfo"}},"required":["results","pagination"]}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication using JWT tokens from Ory Kratos/Hydra"},"OAuth2":{"type":"oauth2","description":"OAuth2 authentication for client applications","flows":{"clientCredentials":{"tokenUrl":"/oauth2/token","scopes":{"api.read":"Read access to API resources","api.write":"Write access to API resources","api.task":"Task execution access","project:view":"View project resources","project:edit":"Edit project resources","project:admin":"Administer project"}},"authorizationCode":{"authorizationUrl":"/oauth2/auth","tokenUrl":"/oauth2/token","scopes":{"openid":"OpenID Connect scope","profile":"User profile access","email":"User email access"}}}},"ApiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use format: Bearer {api_key}"}},"responses":{"BadRequest":{"description":"Bad Request - Invalid input parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized - Missing or invalid authentication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found - Resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"servers":[{"url":"https://app.rightbrain.ai/api/v1","description":"Production API"},{"url":"https://stag.leftbrain.me/api/v1","description":"Staging API"},{"url":"https://app.rblocal.dev/api/v1","description":"Local development"}],"externalDocs":{"description":"API Documentation","url":"https://docs.rightbrain.ai/api"},"x-tag-groups":[{"name":"Core Resources","tags":["Tasks","Projects","Organizations","Users"]},{"name":"AI Features","tags":["Compose","MCP Server","MCP Run","Task Agent Shares"]},{"name":"Data Management","tags":["Document","Collection","Tags","Reporting Groups","Audit Events"]},{"name":"Authentication","tags":["OAuth Clients","API Keys"]},{"name":"System","tags":["Public","Internal","Metadata","Listings"]}]}