[ { "type": "function", "function": { "name": "list_tenants", "description": "List Tenants", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns tenants with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterEmail": { "type": "string", "description": "Returns tenants matching the given email address." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" }, "countBy": { "type": "string", "description": "Specifies the filed to retrieve. Used for traditional pagination." } } } } }, { "type": "function", "function": { "name": "create_tenant", "description": "Create Tenant", "parameters": { "title": "CreateTenantRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateTenantRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "tenants" ] }, "attributes": { "title": "TenantAttributesSchema", "type": "object", "required": [ "name", "email", "plan" ], "properties": { "name": { "type": "string" }, "username": { "type": "string" }, "email": { "type": "string", "format": "email", "minLength": 5, "maxLength": 255 }, "status": { "type": "string" }, "shortCode": { "type": "string", "description": "Tenant short code - the tenant's global handle. NEW codes must be 3-32 lowercase letters/digits (no hyphens; server-validated) and are globally unique (claim registry; duplicates are rejected with 400). Derives the virtual employee's default address boe.{shortCode}@ai.{domain}. Immutable after create. Legacy tenants may carry a '-{n}'-suffixed value." }, "archivedAt": { "type": "string", "format": "date-time", "description": "ISO timestamp the tenant was archived (soft-deleted). Present only on archived/purging tenants; null otherwise. The deletion deadline is archivedAt + the retention window (90 days on prod/test)." }, "deleteAt": { "type": "string", "format": "date-time", "description": "Computed deadline after which an archived tenant is automatically and permanently purged (= archivedAt + the environment's retention window). Null while the tenant is active. Backend-computed and environment-correct, so clients render it directly without hardcoding the retention window. The hourly sweeper collects tenants past this deadline, so the actual purge lands within ~1h after it." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "phone": { "type": "string" }, "address": { "title": "TenantAttributesAddressSchema", "type": "object", "properties": { "county": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "postalcode": { "type": "string" }, "street": { "type": "string" } } }, "settings": { "title": "TenantAttributesSettingsSchema", "type": "object", "properties": { "ad": { "type": "object" }, "brand": { "type": "object", "description": "Brand rules the ad and careers generators read. Split by who can\nact on what: exact colours are applied by CODE (an image model\nonly ever approximates a hex), while the look-and-feel strings\nare fed to the image prompt. Keys: primaryColor / secondaryColor\n(^#[0-9a-fA-F]{6}$), photography, avoid, tone. Freeform for now;\na dedicated brand service is the endgame once logo variants,\ntypefaces and versioning arrive." }, "conversation": { "type": "object" }, "report": { "type": "object" }, "email": { "type": "object" }, "operation": { "type": "object", "description": "Tenant-level outbound-sync defaults (ATS integrations): {syncStage, syncNotes, syncRatings, syncTags, syncReports, syncConversationReports, syncMessages} - overridden per job by job.settings.operation. NOTE: the generated model whitelists keys, so this property MUST be declared for the SDK to carry it." }, "feedback": { "title": "TenantAttributesSettingsFeedbackSchema", "type": "object", "description": "Organisation-wide switch for outbound candidate feedback. Absent = enabled. enabled=false makes feedback:resolve return enabled=false with reason disabled:tenant BEFORE any policy lookup; default and per-job feedback rows stay stored and come back to life when re-enabled. Explicitly validated: enabled must be a JSON boolean (a string is a 400). NOTE: the generated model whitelists keys, so this property MUST be declared for the SDK to carry it.", "properties": { "enabled": { "type": "boolean" } } }, "sso": { "type": "object", "description": "Enterprise SSO configuration. READ-ONLY here: the generic tenant PATCH strips this key, the only writers are the /v1/tenants/{tenantId}/sso doors. Sending it in a PATCH is ignored (not an error).", "properties": { "enabled": { "type": "boolean", "description": "Whether enterprise SSO is provisioned for this tenant" }, "provider": { "type": "string", "enum": [ "microsoft" ], "description": "Identity provider family behind the tenant's IdP" }, "entraTenantId": { "type": "string", "description": "GUID of the customer's Entra tenant. One Cognito IdP serves exactly one Entra tenant: Cognito compares the token iss to a single configured issuer, and Entra mints iss per tenant, so a multi-tenant issuer can never match." }, "idpName": { "type": "string", "description": "Name of the Cognito identity provider, ms-{shortCode}. Carries the tenant, which is how the auth triggers resolve it without scanning." }, "domains": { "type": "array", "description": "Email domains of the customer. A domain gates JIT and auto-link ONLY once it carries verifiedAt - uniqueness in the claim registry is not proof of ownership.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "verifiedAt": { "type": "string" }, "method": { "type": "string", "enum": [ "ops-confirmed", "dns-txt", "entra-verified" ] } } } }, "defaultRole": { "type": "string", "description": "Role granted when a pending JIT user is APPROVED - never granted by the act of signing in. Domain-gated JIT makes the whole customer workforce eligible, so an automatic operational role would expose candidate data to anyone who can authenticate at the customer's IdP." }, "required": { "type": "boolean", "description": "When true, password login is refused for this tenant's users. Owner and sysowner are always exempt - a break-glass account, because an outage in the customer's Entra must not lock them out of the product." }, "autoApprove": { "type": "boolean", "description": "When true, a JIT user is activated immediately with defaultRole instead of landing in a pending state. Off by default." } } }, "language": { "type": "string", "pattern": "^[a-z]{2}-[A-Z]{2}$", "description": "THE ORGANISATION'S OWN LANGUAGE - the tenant-level default\nevery surface falls back to when nothing more specific says\notherwise. BCP-47 (`pl-PL`, not `pl`). Supported today:\nen-US, pl-PL, de-DE, it-IT, fr-FR, cs-CZ, he-IL.\n\nDistinct from `activeLanguages`, which is an UNORDERED SET of\nthe locales a tenant publishes in and carries no notion of a\nprimary one - never read `activeLanguages[0]` as the default.\nAlso distinct from a user's Cognito `locale`, which is one\nrecruiter's interface language.\n\nRead by the outbound-email locale chain, conversation\nlanguage, meeting lobby locale, careers `sourceLanguage` at\ncreate, and the translation target of the file/talent/\npersona/timeline/report AI paths. Onboarding seeds every new\nuser's Cognito locale from it.\n\nClient-writable through tenant create/PATCH (settings merge\nis shallow, so sending only `language` preserves the other\nsettings keys). NOTE: the server does not yet enforce this\npattern on write - consumers validate defensively and fall\nback to en-US." }, "calling": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether calling is enabled for this tenant" }, "twilioSubaccountSid": { "type": "string", "description": "Twilio subaccount SID for this tenant" }, "twilioPhoneNumber": { "type": "string", "description": "Provisioned Twilio phone number" }, "twilioPhoneSid": { "type": "string", "description": "Twilio phone number SID" }, "phoneNumber": { "type": "string", "description": "Provisioned phone number for non-twilio providers (telnyx/external)" }, "telnyxPhoneNumberId": { "type": "string", "description": "Telnyx phone number id (provider telnyx)" }, "provider": { "type": "string", "enum": [ "twilio", "telnyx", "external" ], "description": "Which provider hosts the calling number" }, "capabilities": { "type": "object", "description": "Capability snapshot of the calling number, stamped at assign. Absent on pre-capability assignments.", "properties": { "voice": { "type": "boolean" }, "sms": { "type": "boolean" }, "mms": { "type": "boolean" } } }, "provisionedAt": { "type": "string", "format": "date-time", "description": "When calling was provisioned" } } }, "messaging": { "type": "object", "description": "Optional dedicated SMS number (messaging slot). Absent = SMS rides the calling number. Outbound SMS prefers this number; it is never a voice caller-ID and never the virtual employee's phone.", "properties": { "phoneNumber": { "type": "string", "description": "The dedicated SMS number (E.164)" }, "provider": { "type": "string", "enum": [ "twilio", "telnyx", "external" ] }, "twilioPhoneSid": { "type": "string" }, "telnyxPhoneNumberId": { "type": "string" }, "enabled": { "type": "boolean" }, "capabilities": { "type": "object", "description": "Capability snapshot stamped at assign", "properties": { "voice": { "type": "boolean" }, "sms": { "type": "boolean" }, "mms": { "type": "boolean" } } } } }, "limits": { "type": "object", "description": "Anti-abuse limits for the inbound-call channel (inbound-call arc). Declared ahead of enforcement so generated clients carry the key (the typed settings schema is a whitelist - undeclared keys are silently dropped by the SDK). Sysowner-only on PATCH (cost-protection config, the boeMetering precedent); values are inert until the P4 limiter ships.", "properties": { "callsPerCliHour": { "type": "integer", "minimum": 1, "description": "Max inbound calls per caller number per hour" }, "callsPerCliDay": { "type": "integer", "minimum": 1, "description": "Max inbound calls per caller number per day" }, "callMinutesDailyBudget": { "type": "integer", "minimum": 1, "description": "Daily inbound AI-call minutes budget for the tenant" }, "maxConcurrentInboundCalls": { "type": "integer", "minimum": 1 }, "maxCallDurationMinutes": { "type": "integer", "minimum": 1, "description": "Hard cap on one intake conversation" }, "smsPerNumberDay": { "type": "integer", "minimum": 1, "description": "Max outbound SMS to one number per day (phase-2 rails)" }, "smsDailyBudget": { "type": "integer", "minimum": 1, "description": "Daily outbound-SMS budget for the tenant across the inbound-call channel (2b rails; container default applies when unset)" } } } } }, "plan": { "type": "string", "minLength": 1, "maxLength": 255, "enum": [ "startup", "growth", "expansion", "corporate", "system" ], "description": "Billing plan. The API Gateway authorizer maps custom:userPlan onto a usage plan key and falls back to `system` - the PLATFORM's own plan - for anything it does not recognise, so an invented name does not fail, it silently meters that customer against our internal quota. `enterprise` was such a name (a second word for `corporate`) and was folded into it 2026-07-27. NOTE: the server checks this list explicitly, because validate_item honours type/pattern/length but IGNORES enum." }, "activeLanguages": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2}-[A-Z]{2}$" } }, "trialExpiryDate": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "logoUrl": { "type": "string" }, "boePhone": { "type": "string", "deprecated": true, "description": "DEPRECATED (Arc B B3d): the virtual employee's phone lives on its USER row - read it via the tenant's boeUser relationship. Tenant responses no longer carry this attribute." }, "boeEmail": { "type": "string", "deprecated": true, "description": "DEPRECATED (Arc B B3d): the virtual employee's email lives on its USER row - read it via the tenant's boeUser relationship. Tenant responses no longer carry this attribute; client-supplied values are ignored." }, "defaultFormId": { "type": "string", "deprecated": true, "description": "DEPRECATED (talent-pool arc): no writer exists and the tenant PATCH ignores it - the per-kind default lives in tenant.relationships.forms (talentSubmission pin surfaces publicly as careers.json talentPool). Client-supplied values are ignored." } } }, "relationships": { "title": "TenantRelationshipsSchema", "type": "object", "properties": { "boeUser": { "title": "TenantRelationshipsBoeUserSchema", "type": "object", "description": "The Boe AI user account for this tenant. Used as the system principal for guest-initiated workflows (apply forms, inbound emails, inbound calls) where no authenticated user exists. Set during tenant onboarding; not client-writable via tenant PATCH.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "boeCalendar": { "title": "TenantRelationshipsBoeCalendarSchema", "type": "object", "description": "Boe's primary calendar. Denormalized here so workflow seeds and FE can resolve it in one tenant fetch instead of a list_calendars round trip. Mirror of boeUser semantics: written by tenant onboarding / workflow seeding, not client-writable via tenant PATCH. May be null on tenants provisioned before boe calendars existed - fall back to GET /v1/calendars?filterOwnerId=boeUserId.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "feedbacks": { "title": "TenantRelationshipsFeedbacksSchema", "type": "object", "description": "Tenant-wide default feedback configurations. Up to one per stage (screening, assessment, interview). Used when the job has no stage-specific feedback override. Only sendable rows (status active or accepted) may be pinned here; archived/draft/failed ids are rejected with 400.", "properties": { "data": { "type": "array", "items": { "title": "TenantRelationshipsFeedbacksDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "forms": { "title": "TenantRelationshipsFormsSchema", "type": "object", "description": "Tenant-wide default forms per kind. Up to one form per FormKind value (jobBrief, candidateSubmission, talentSubmission, general). Designates which form's schema is canonical for each intake channel - the inbound email agent reads this to find the form whose fields it should populate when creating a brief.", "properties": { "data": { "type": "array", "items": { "title": "TenantRelationshipsFormsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "tenants_options", "description": "Tenants Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_tenant", "description": "Show Tenant", "parameters": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "The tenant's identifier" }, "include": { "type": "string", "description": "JSON:API compound document request - comma-separated list of relationship paths to include in the response (e.g. `feedbacks`, `feedbacks,boeUser`). Currently advisory: the service always returns all declared relationships with empty defaults." } }, "required": [ "tenantId" ] } } }, { "type": "function", "function": { "name": "update_tenant", "description": "Update Tenant", "parameters": { "title": "UpdateTenantRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateTenantRequestBodyData", "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "tenants" ] }, "id": { "type": "string" }, "attributes": { "title": "TenantAttributesSchema", "type": "object", "required": [ "name", "email", "plan" ], "properties": { "name": { "type": "string" }, "username": { "type": "string" }, "email": { "type": "string", "format": "email", "minLength": 5, "maxLength": 255 }, "status": { "type": "string" }, "shortCode": { "type": "string", "description": "Tenant short code - the tenant's global handle. NEW codes must be 3-32 lowercase letters/digits (no hyphens; server-validated) and are globally unique (claim registry; duplicates are rejected with 400). Derives the virtual employee's default address boe.{shortCode}@ai.{domain}. Immutable after create. Legacy tenants may carry a '-{n}'-suffixed value." }, "archivedAt": { "type": "string", "format": "date-time", "description": "ISO timestamp the tenant was archived (soft-deleted). Present only on archived/purging tenants; null otherwise. The deletion deadline is archivedAt + the retention window (90 days on prod/test)." }, "deleteAt": { "type": "string", "format": "date-time", "description": "Computed deadline after which an archived tenant is automatically and permanently purged (= archivedAt + the environment's retention window). Null while the tenant is active. Backend-computed and environment-correct, so clients render it directly without hardcoding the retention window. The hourly sweeper collects tenants past this deadline, so the actual purge lands within ~1h after it." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "phone": { "type": "string" }, "address": { "title": "TenantAttributesAddressSchema", "type": "object", "properties": { "county": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "postalcode": { "type": "string" }, "street": { "type": "string" } } }, "settings": { "title": "TenantAttributesSettingsSchema", "type": "object", "properties": { "ad": { "type": "object" }, "brand": { "type": "object", "description": "Brand rules the ad and careers generators read. Split by who can\nact on what: exact colours are applied by CODE (an image model\nonly ever approximates a hex), while the look-and-feel strings\nare fed to the image prompt. Keys: primaryColor / secondaryColor\n(^#[0-9a-fA-F]{6}$), photography, avoid, tone. Freeform for now;\na dedicated brand service is the endgame once logo variants,\ntypefaces and versioning arrive." }, "conversation": { "type": "object" }, "report": { "type": "object" }, "email": { "type": "object" }, "operation": { "type": "object", "description": "Tenant-level outbound-sync defaults (ATS integrations): {syncStage, syncNotes, syncRatings, syncTags, syncReports, syncConversationReports, syncMessages} - overridden per job by job.settings.operation. NOTE: the generated model whitelists keys, so this property MUST be declared for the SDK to carry it." }, "feedback": { "title": "TenantAttributesSettingsFeedbackSchema", "type": "object", "description": "Organisation-wide switch for outbound candidate feedback. Absent = enabled. enabled=false makes feedback:resolve return enabled=false with reason disabled:tenant BEFORE any policy lookup; default and per-job feedback rows stay stored and come back to life when re-enabled. Explicitly validated: enabled must be a JSON boolean (a string is a 400). NOTE: the generated model whitelists keys, so this property MUST be declared for the SDK to carry it.", "properties": { "enabled": { "type": "boolean" } } }, "sso": { "type": "object", "description": "Enterprise SSO configuration. READ-ONLY here: the generic tenant PATCH strips this key, the only writers are the /v1/tenants/{tenantId}/sso doors. Sending it in a PATCH is ignored (not an error).", "properties": { "enabled": { "type": "boolean", "description": "Whether enterprise SSO is provisioned for this tenant" }, "provider": { "type": "string", "enum": [ "microsoft" ], "description": "Identity provider family behind the tenant's IdP" }, "entraTenantId": { "type": "string", "description": "GUID of the customer's Entra tenant. One Cognito IdP serves exactly one Entra tenant: Cognito compares the token iss to a single configured issuer, and Entra mints iss per tenant, so a multi-tenant issuer can never match." }, "idpName": { "type": "string", "description": "Name of the Cognito identity provider, ms-{shortCode}. Carries the tenant, which is how the auth triggers resolve it without scanning." }, "domains": { "type": "array", "description": "Email domains of the customer. A domain gates JIT and auto-link ONLY once it carries verifiedAt - uniqueness in the claim registry is not proof of ownership.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "verifiedAt": { "type": "string" }, "method": { "type": "string", "enum": [ "ops-confirmed", "dns-txt", "entra-verified" ] } } } }, "defaultRole": { "type": "string", "description": "Role granted when a pending JIT user is APPROVED - never granted by the act of signing in. Domain-gated JIT makes the whole customer workforce eligible, so an automatic operational role would expose candidate data to anyone who can authenticate at the customer's IdP." }, "required": { "type": "boolean", "description": "When true, password login is refused for this tenant's users. Owner and sysowner are always exempt - a break-glass account, because an outage in the customer's Entra must not lock them out of the product." }, "autoApprove": { "type": "boolean", "description": "When true, a JIT user is activated immediately with defaultRole instead of landing in a pending state. Off by default." } } }, "language": { "type": "string", "pattern": "^[a-z]{2}-[A-Z]{2}$", "description": "THE ORGANISATION'S OWN LANGUAGE - the tenant-level default\nevery surface falls back to when nothing more specific says\notherwise. BCP-47 (`pl-PL`, not `pl`). Supported today:\nen-US, pl-PL, de-DE, it-IT, fr-FR, cs-CZ, he-IL.\n\nDistinct from `activeLanguages`, which is an UNORDERED SET of\nthe locales a tenant publishes in and carries no notion of a\nprimary one - never read `activeLanguages[0]` as the default.\nAlso distinct from a user's Cognito `locale`, which is one\nrecruiter's interface language.\n\nRead by the outbound-email locale chain, conversation\nlanguage, meeting lobby locale, careers `sourceLanguage` at\ncreate, and the translation target of the file/talent/\npersona/timeline/report AI paths. Onboarding seeds every new\nuser's Cognito locale from it.\n\nClient-writable through tenant create/PATCH (settings merge\nis shallow, so sending only `language` preserves the other\nsettings keys). NOTE: the server does not yet enforce this\npattern on write - consumers validate defensively and fall\nback to en-US." }, "calling": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether calling is enabled for this tenant" }, "twilioSubaccountSid": { "type": "string", "description": "Twilio subaccount SID for this tenant" }, "twilioPhoneNumber": { "type": "string", "description": "Provisioned Twilio phone number" }, "twilioPhoneSid": { "type": "string", "description": "Twilio phone number SID" }, "phoneNumber": { "type": "string", "description": "Provisioned phone number for non-twilio providers (telnyx/external)" }, "telnyxPhoneNumberId": { "type": "string", "description": "Telnyx phone number id (provider telnyx)" }, "provider": { "type": "string", "enum": [ "twilio", "telnyx", "external" ], "description": "Which provider hosts the calling number" }, "capabilities": { "type": "object", "description": "Capability snapshot of the calling number, stamped at assign. Absent on pre-capability assignments.", "properties": { "voice": { "type": "boolean" }, "sms": { "type": "boolean" }, "mms": { "type": "boolean" } } }, "provisionedAt": { "type": "string", "format": "date-time", "description": "When calling was provisioned" } } }, "messaging": { "type": "object", "description": "Optional dedicated SMS number (messaging slot). Absent = SMS rides the calling number. Outbound SMS prefers this number; it is never a voice caller-ID and never the virtual employee's phone.", "properties": { "phoneNumber": { "type": "string", "description": "The dedicated SMS number (E.164)" }, "provider": { "type": "string", "enum": [ "twilio", "telnyx", "external" ] }, "twilioPhoneSid": { "type": "string" }, "telnyxPhoneNumberId": { "type": "string" }, "enabled": { "type": "boolean" }, "capabilities": { "type": "object", "description": "Capability snapshot stamped at assign", "properties": { "voice": { "type": "boolean" }, "sms": { "type": "boolean" }, "mms": { "type": "boolean" } } } } }, "limits": { "type": "object", "description": "Anti-abuse limits for the inbound-call channel (inbound-call arc). Declared ahead of enforcement so generated clients carry the key (the typed settings schema is a whitelist - undeclared keys are silently dropped by the SDK). Sysowner-only on PATCH (cost-protection config, the boeMetering precedent); values are inert until the P4 limiter ships.", "properties": { "callsPerCliHour": { "type": "integer", "minimum": 1, "description": "Max inbound calls per caller number per hour" }, "callsPerCliDay": { "type": "integer", "minimum": 1, "description": "Max inbound calls per caller number per day" }, "callMinutesDailyBudget": { "type": "integer", "minimum": 1, "description": "Daily inbound AI-call minutes budget for the tenant" }, "maxConcurrentInboundCalls": { "type": "integer", "minimum": 1 }, "maxCallDurationMinutes": { "type": "integer", "minimum": 1, "description": "Hard cap on one intake conversation" }, "smsPerNumberDay": { "type": "integer", "minimum": 1, "description": "Max outbound SMS to one number per day (phase-2 rails)" }, "smsDailyBudget": { "type": "integer", "minimum": 1, "description": "Daily outbound-SMS budget for the tenant across the inbound-call channel (2b rails; container default applies when unset)" } } } } }, "plan": { "type": "string", "minLength": 1, "maxLength": 255, "enum": [ "startup", "growth", "expansion", "corporate", "system" ], "description": "Billing plan. The API Gateway authorizer maps custom:userPlan onto a usage plan key and falls back to `system` - the PLATFORM's own plan - for anything it does not recognise, so an invented name does not fail, it silently meters that customer against our internal quota. `enterprise` was such a name (a second word for `corporate`) and was folded into it 2026-07-27. NOTE: the server checks this list explicitly, because validate_item honours type/pattern/length but IGNORES enum." }, "activeLanguages": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2}-[A-Z]{2}$" } }, "trialExpiryDate": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "logoUrl": { "type": "string" }, "boePhone": { "type": "string", "deprecated": true, "description": "DEPRECATED (Arc B B3d): the virtual employee's phone lives on its USER row - read it via the tenant's boeUser relationship. Tenant responses no longer carry this attribute." }, "boeEmail": { "type": "string", "deprecated": true, "description": "DEPRECATED (Arc B B3d): the virtual employee's email lives on its USER row - read it via the tenant's boeUser relationship. Tenant responses no longer carry this attribute; client-supplied values are ignored." }, "defaultFormId": { "type": "string", "deprecated": true, "description": "DEPRECATED (talent-pool arc): no writer exists and the tenant PATCH ignores it - the per-kind default lives in tenant.relationships.forms (talentSubmission pin surfaces publicly as careers.json talentPool). Client-supplied values are ignored." } } }, "relationships": { "title": "TenantRelationshipsSchema", "type": "object", "properties": { "boeUser": { "title": "TenantRelationshipsBoeUserSchema", "type": "object", "description": "The Boe AI user account for this tenant. Used as the system principal for guest-initiated workflows (apply forms, inbound emails, inbound calls) where no authenticated user exists. Set during tenant onboarding; not client-writable via tenant PATCH.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "boeCalendar": { "title": "TenantRelationshipsBoeCalendarSchema", "type": "object", "description": "Boe's primary calendar. Denormalized here so workflow seeds and FE can resolve it in one tenant fetch instead of a list_calendars round trip. Mirror of boeUser semantics: written by tenant onboarding / workflow seeding, not client-writable via tenant PATCH. May be null on tenants provisioned before boe calendars existed - fall back to GET /v1/calendars?filterOwnerId=boeUserId.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "feedbacks": { "title": "TenantRelationshipsFeedbacksSchema", "type": "object", "description": "Tenant-wide default feedback configurations. Up to one per stage (screening, assessment, interview). Used when the job has no stage-specific feedback override. Only sendable rows (status active or accepted) may be pinned here; archived/draft/failed ids are rejected with 400.", "properties": { "data": { "type": "array", "items": { "title": "TenantRelationshipsFeedbacksDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "forms": { "title": "TenantRelationshipsFormsSchema", "type": "object", "description": "Tenant-wide default forms per kind. Up to one form per FormKind value (jobBrief, candidateSubmission, talentSubmission, general). Designates which form's schema is canonical for each intake channel - the inbound email agent reads this to find the form whose fields it should populate when creating a brief.", "properties": { "data": { "type": "array", "items": { "title": "TenantRelationshipsFormsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_tenant", "description": "Delete Tenant", "parameters": { "type": "object", "properties": { "permanentDelete": { "type": "string", "description": "Set to true for immediate irreversible purge of all tenant data. Defaults to false (soft archive with a retention window).", "enum": [ "true", "false" ] } } } } }, { "type": "function", "function": { "name": "tenant_options", "description": "Tenant Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "create_tenant_upload", "description": "Create Tenant Upload", "parameters": { "title": "CreateTenantUploadRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateTenantUploadRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "tenant-uploads" ] }, "attributes": { "type": "object", "required": [ "extension", "purpose" ], "properties": { "extension": { "type": "string", "enum": [ "png", "jpg", "jpeg", "webp" ] }, "purpose": { "type": "string", "enum": [ "logo", "background", "favicon", "careers" ] } } } } } } } } }, { "type": "function", "function": { "name": "tenant_uploads_options", "description": "Tenant Uploads Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "search_tenant_phone_numbers", "description": "Search Available Phone Numbers", "parameters": { "type": "object", "properties": { "country": { "type": "string", "description": "ISO country code" }, "areaCode": { "type": "string", "description": "Area code to search" }, "contains": { "type": "string", "description": "Pattern to match in phone number" } } } } }, { "type": "function", "function": { "name": "tenant_phone_numbers_search_options", "description": "Phone Numbers Search Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "assign_tenant_phone_number", "description": "Assign Existing Phone Number", "parameters": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tenant-phone-numbers" ] }, "attributes": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "The phone number to assign (E.164 format)" }, "provider": { "type": "string", "enum": [ "twilio", "telnyx", "external" ], "default": "twilio", "description": "Where the number is hosted" }, "capabilities": { "type": "object", "description": "Channel capabilities of the number. Only honored for provider external (twilio/telnyx read them from the provider); undeclared fields default to false.", "properties": { "voice": { "type": "boolean" }, "sms": { "type": "boolean" }, "mms": { "type": "boolean" } } }, "slot": { "type": "string", "enum": [ "calling", "messaging" ], "default": "calling", "description": "Channel slot: calling = voice identity number (default), messaging = dedicated SMS number (requires SMS capability)" } }, "required": [ "phoneNumber" ] } } } } } } }, { "type": "function", "function": { "name": "tenant_phone_numbers_assign_options", "description": "Assign Phone Number Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "unassign_tenant_phone_number", "description": "Unassign Phone Number", "parameters": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tenant-phone-numbers" ] }, "attributes": { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "calling", "messaging" ], "default": "calling", "description": "Which slot to detach" } } } } } } } } }, { "type": "function", "function": { "name": "tenant_phone_numbers_unassign_options", "description": "Unassign Phone Number Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_tenant_sso", "description": "Show Tenant Enterprise SSO", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "configure_tenant_sso", "description": "Configure Tenant Enterprise SSO", "parameters": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tenant-sso" ] }, "attributes": { "title": "TenantSsoAttributesSchema", "type": "object", "description": "Enterprise SSO configuration for one tenant. The connection itself is written only by POST /v1/tenants/{tenantId}/sso (sysowner); the policy subset in TenantSsoPolicySchema is also reachable by the tenant's owner through PATCH. The generic tenant PATCH strips settings.sso.", "properties": { "provider": { "type": "string", "enum": [ "microsoft" ], "description": "Identity provider family behind the tenant's IdP" }, "entraTenantId": { "type": "string", "description": "GUID of the customer's Entra tenant. One Cognito IdP serves exactly one Entra tenant: Cognito compares the token iss to a single configured issuer and Entra mints iss per tenant, so a multi-tenant issuer can never match. NOTE: CreateIdentityProvider accepts a /common issuer without error and only sign-in fails, which is why 'common' is rejected here." }, "idpName": { "type": "string", "description": "Derived server-side as ms-{shortCode} and ignored if sent. The name carries the tenant, which is how the auth triggers resolve it without scanning; it must fit Cognito's 32-character IdP name limit." }, "domains": { "type": "array", "description": "Email domains of the customer. A domain gates JIT and auto-link ONLY once it carries verifiedAt - uniqueness in the claim registry is not proof of ownership. Public mail providers (gmail.com and friends) are rejected: a shared domain can never prove its holder employs the person signing in.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "verifiedAt": { "type": "string" }, "method": { "type": "string", "enum": [ "ops-confirmed", "dns-txt", "entra-verified" ] } } } }, "defaultRole": { "type": "string", "description": "Role granted when a pending JIT user is APPROVED - never granted by the act of signing in. Domain-gated JIT makes the whole customer workforce eligible, so an automatic operational role would expose candidate data to anyone who can authenticate at the customer's IdP. Privileged roles (owner/admin/sysowner) are rejected." }, "required": { "type": "boolean", "description": "When true, password login is refused for this tenant's users. Owner and sysowner are always exempt - a break-glass account, because an outage in the customer's Entra must not lock them out of the product." }, "autoApprove": { "type": "boolean", "description": "When true, a JIT user is activated immediately with defaultRole instead of landing in a pending state. Off by default." }, "enabled": { "type": "boolean", "description": "Whether a Cognito identity provider exists for this tenant. Owned by the provisioning step and ignored if sent." }, "adminConsentUrl": { "type": "string", "description": "The admin-consent link an operator sends to the customer's IT. Built server-side so the app registration id is never hardcoded in a client. Absent if the platform Microsoft provider cannot be read." }, "sessionsRevoked": { "type": "integer", "description": "POST response, present ONLY on the transition to required=true: how many accounts were signed out everywhere. The PreAuthentication gate stops new password sign-ins but never fires on token refresh, and a refresh token lives 30 days - so without this sweep the switch would take a month to take effect for anyone already signed in. Nobody is exempt, including the break-glass roles: they keep their password and simply sign in again." }, "sessionsFailed": { "type": "integer", "description": "POST response, alongside sessionsRevoked: accounts the sweep could not sign out. Non-zero means the door is partially open - those sessions keep working until their refresh token expires - and the operator is the only one positioned to see it, which is why it is returned rather than only logged." }, "idpDeleted": { "type": "boolean", "description": "DELETE response only: whether the customer's Cognito identity provider was actually removed. False when it was already gone, so a retry of the teardown reads as success rather than an error." }, "domainsReleased": { "type": "array", "description": "DELETE response only: the domains freed in the global claim registry, i.e. the ones another tenant may now claim. Empty when the tenant held none or another tenant owned them.", "items": { "type": "string" } }, "loginUrl": { "type": "string", "description": "Ready-made login link for this customer's employees (a tile in their Entra My Apps, an intranet bookmark, the welcome email), of the form https://myaccount.{domain}/sso?idp=ms-{shortCode}. It points at the APP, never at Cognito's authorize endpoint: nextauth refuses a callback it did not initiate, because the state, nonce and PKCE verifier it validates against live in cookies it sets while building the authorize URL itself - a hand-assembled Cognito link fails with 'State cookie was missing' however correct its parameters are. The page forwards idp as identity_provider, which also keeps the enterprise client's hosted page from drawing a button for every customer IdP on it. There is deliberately no email-domain discovery endpoint: Cognito's own domain routing is SAML-only, and a public discovery endpoint would be an oracle for whether a given company is our customer. Lands in the myaccount app, which every role can reach - a JIT employee in the pending state has no role yet, so a role-scoped app would refuse them and the link would look broken. Derived on read, never stored." } } } } } } } } }, { "type": "function", "function": { "name": "update_tenant_sso", "description": "Update Tenant Enterprise SSO Policy", "parameters": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tenant-sso" ] }, "attributes": { "title": "TenantSsoPolicySchema", "type": "object", "description": "The policy a customer's OWNER may set on top of an existing SSO connection (PATCH /v1/tenants/{tenantId}/sso). Deliberately a subset: these three fields reach nothing outside the tenant, whereas `domains` claims a name in a GLOBAL registry that phase 1 verifies by hand, and `entraTenantId`/`idpName` identify the connection itself - those stay on the sysowner-only POST. Every field is optional; whatever is omitted keeps its stored value.", "properties": { "required": { "type": "boolean", "description": "When true, password login is refused for this tenant's users. Owner and sysowner are always exempt (a break-glass account: an outage at the customer's IdP must not lock them out of the product, or out of this door), as is any user carrying meta.ssoExempt. Switching it from false to true also signs every account out - the enforcement trigger never sees a token refresh, and a refresh token lives 30 days." }, "autoApprove": { "type": "boolean", "description": "When true, a JIT user is activated immediately with defaultRole instead of landing in a pending state. Off by default: domain-gated JIT makes the customer's whole workforce eligible, so this hands an operational role to anyone who can authenticate at their IdP." }, "defaultRole": { "type": "string", "description": "Role granted when a pending JIT user is APPROVED - never granted by the act of signing in." } } } } } } } } }, { "type": "function", "function": { "name": "delete_tenant_sso", "description": "Delete Tenant Enterprise SSO", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "tenant_sso_options", "description": "Tenant SSO Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "purchase_tenant_phone_number", "description": "Purchase Phone Number", "parameters": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tenant-phone-numbers" ] }, "attributes": { "type": "object", "properties": { "phoneNumber": { "type": "string", "description": "The phone number to purchase (E.164 format)" } }, "required": [ "phoneNumber" ] } } } } } } }, { "type": "function", "function": { "name": "release_tenant_phone_number", "description": "Release Phone Number", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "tenant_phone_numbers_options", "description": "Phone Numbers Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_users", "description": "List Users", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns users with this status. Omitting it returns EVERY status - the server applies no default, so `pending` accounts already appear in an unfiltered list. `pending` is the approval queue: a JIT user provisioned through enterprise SSO lands there and holds no tenant claims at all until an owner or admin flips them to active.", "enum": [ "active", "archived", "pending" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_user", "description": "Create User", "parameters": { "title": "CreateUserRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateUserRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "users" ] }, "attributes": { "title": "UserAttributesSchema", "type": "object", "required": [ "name", "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "gender": { "type": "string" }, "locale": { "type": "string" }, "phone": { "type": "string" }, "isSystem": { "type": "boolean", "description": "Marks tenant-internal system users (admins, integrations, the Boe bot). Distinct from `type` - `isSystem=true` only means 'not a regular end-user'; the human-vs-bot split lives in `type`." }, "type": { "type": "string", "enum": [ "human", "ai" ], "description": "Discriminator for human-vs-bot users.\n 'ai' - Boe bot user. tenant.relationships.boeUser points at one\n of these per tenant. Drives the createMeetingAttendee\n AI-dispatch decision: principalType=user + user.type='ai'\n makes the meeting service spawn a Fargate bot instead of\n returning Chime join credentials.\n 'human' - regular user (recruiter, observer, candidate-with-account).\n null - legacy rows without the field; treated as 'human' by the\n server (safer default - we'd rather miss a bot dispatch\n than accidentally dispatch a Fargate task for a real human)." }, "address": { "type": "object", "additionalProperties": true }, "settings": { "type": "object", "additionalProperties": true, "description": "Free-form user settings map. PATCH replaces the WHOLE object -\nclients must read-merge-write. On the virtual employee\n(type='ai') the `presence` key is the canonical audio-visual\nidentity contract (Arc B B4.2), sparse by design: an absent\nkey means \"use the channel's default\".", "properties": { "presence": { "type": "object", "description": "Virtual-employee AV identity. Read-side resolver\n(presence_utils) sanitizes: voiceId/liveAvatarId must be\nplain tokens ([A-Za-z0-9._-], max 64/128) else they degrade\nto the channel default; intro is capped at 300 code points\non read. Consumed by meeting dispatch, the webapp realtime\nmint and call TwiML.", "properties": { "voiceId": { "type": "string", "description": "Realtime voice for EVERY channel the employee speaks in: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar. Backend only format-validates - FE should offer the hard list." }, "voiceGender": { "type": "string", "enum": [ "male", "female" ] }, "liveAvatarId": { "type": "string", "description": "HeyGen LiveAvatar id for on-grid video." }, "intro": { "type": "string", "maxLength": 300, "description": "Character sketch appended to voice prompts. NOT a role prompt (persona service owns prompt configs)." } } } } }, "connections": { "type": "object", "additionalProperties": true }, "identities": { "type": "array", "description": "Federated logins linked to this account. System-owned: written only by the auth triggers and the linking doors, never by a PATCH. Linking must happen BEFORE the first federated sign-in, otherwise Cognito mints a separate profile that has to be deleted.", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Cognito identity provider name (Google, LinkedIn, or ms-{shortCode})" }, "sub": { "type": "string", "description": "The provider's subject identifier. Pairwise per client_id at Entra, so it only matches tokens issued to the same app registration as the IdP." }, "linkedAt": { "type": "string" } } } }, "avatarUrl": { "type": "string", "description": "CDN URL of the profile picture. Either a per-user upload (users/... key, minted via the upload door) or a shared gallery image (avatars/...). Must point at an existing CDN object - updateUser head-checks it." }, "sendInvitation": { "type": "boolean", "description": "CREATE-ONLY. Default true: Cognito emails the temporary password. Set false to suppress the invitation - then `password` is required. Requires role sysowner/owner/admin. Rejected on update." }, "password": { "type": "string", "format": "password", "minLength": 8, "description": "CREATE-ONLY, never returned. Admin-set password for the new account; requires `sendInvitation: false` and role sysowner/owner/admin. Must satisfy the pool password policy (min 8, upper+lower+digit+symbol). Rejected on update." }, "passwordPermanent": { "type": "boolean", "description": "CREATE-ONLY. False (default): the account lands in FORCE_CHANGE_PASSWORD and the user must change the password at first sign-in. True: the password is permanent and the account is active immediately (audited)." }, "status": { "type": "string" }, "historyEvents": { "type": "array", "items": { "title": "UserHistoryEventSchema", "type": "object", "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "result": { "type": "string" }, "riskLevel": { "type": "string" }, "riskDecision": { "type": "string" }, "compromisedCredentials": { "type": "boolean" }, "challengeResponses": { "type": "array", "items": { "type": "object", "properties": { "challenge": { "type": "string" }, "result": { "type": "string" } } } }, "ipAddress": { "type": "string" }, "deviceName": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "timezone": { "type": "string" }, "newDeviceUsed": { "type": "boolean" }, "eventFeedback": { "type": "object", "properties": { "feedbackValue": { "type": "string" }, "provider": { "type": "string" } } } } } }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "UserRelationshipsSchema", "type": "object", "properties": { "role": { "title": "UserRelationshipsRoleSchema", "type": "object", "properties": { "data": { "title": "UserRelationshipsRoleDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "jobs": { "title": "UserRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "UserRelationshipsJobsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "apikeys": { "title": "UserRelationshipsApikeysSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "UserRelationshipsApikeysDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "users_options", "description": "Users Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_user", "description": "Show User", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_user", "description": "Update User", "parameters": { "title": "UpdateUserRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateUserRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "users" ] }, "id": { "type": "string" }, "attributes": { "title": "UserAttributesSchema", "type": "object", "required": [ "name", "email" ], "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "gender": { "type": "string" }, "locale": { "type": "string" }, "phone": { "type": "string" }, "isSystem": { "type": "boolean", "description": "Marks tenant-internal system users (admins, integrations, the Boe bot). Distinct from `type` - `isSystem=true` only means 'not a regular end-user'; the human-vs-bot split lives in `type`." }, "type": { "type": "string", "enum": [ "human", "ai" ], "description": "Discriminator for human-vs-bot users.\n 'ai' - Boe bot user. tenant.relationships.boeUser points at one\n of these per tenant. Drives the createMeetingAttendee\n AI-dispatch decision: principalType=user + user.type='ai'\n makes the meeting service spawn a Fargate bot instead of\n returning Chime join credentials.\n 'human' - regular user (recruiter, observer, candidate-with-account).\n null - legacy rows without the field; treated as 'human' by the\n server (safer default - we'd rather miss a bot dispatch\n than accidentally dispatch a Fargate task for a real human)." }, "address": { "type": "object", "additionalProperties": true }, "settings": { "type": "object", "additionalProperties": true, "description": "Free-form user settings map. PATCH replaces the WHOLE object -\nclients must read-merge-write. On the virtual employee\n(type='ai') the `presence` key is the canonical audio-visual\nidentity contract (Arc B B4.2), sparse by design: an absent\nkey means \"use the channel's default\".", "properties": { "presence": { "type": "object", "description": "Virtual-employee AV identity. Read-side resolver\n(presence_utils) sanitizes: voiceId/liveAvatarId must be\nplain tokens ([A-Za-z0-9._-], max 64/128) else they degrade\nto the channel default; intro is capped at 300 code points\non read. Consumed by meeting dispatch, the webapp realtime\nmint and call TwiML.", "properties": { "voiceId": { "type": "string", "description": "Realtime voice for EVERY channel the employee speaks in: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar. Backend only format-validates - FE should offer the hard list." }, "voiceGender": { "type": "string", "enum": [ "male", "female" ] }, "liveAvatarId": { "type": "string", "description": "HeyGen LiveAvatar id for on-grid video." }, "intro": { "type": "string", "maxLength": 300, "description": "Character sketch appended to voice prompts. NOT a role prompt (persona service owns prompt configs)." } } } } }, "connections": { "type": "object", "additionalProperties": true }, "identities": { "type": "array", "description": "Federated logins linked to this account. System-owned: written only by the auth triggers and the linking doors, never by a PATCH. Linking must happen BEFORE the first federated sign-in, otherwise Cognito mints a separate profile that has to be deleted.", "items": { "type": "object", "properties": { "provider": { "type": "string", "description": "Cognito identity provider name (Google, LinkedIn, or ms-{shortCode})" }, "sub": { "type": "string", "description": "The provider's subject identifier. Pairwise per client_id at Entra, so it only matches tokens issued to the same app registration as the IdP." }, "linkedAt": { "type": "string" } } } }, "avatarUrl": { "type": "string", "description": "CDN URL of the profile picture. Either a per-user upload (users/... key, minted via the upload door) or a shared gallery image (avatars/...). Must point at an existing CDN object - updateUser head-checks it." }, "sendInvitation": { "type": "boolean", "description": "CREATE-ONLY. Default true: Cognito emails the temporary password. Set false to suppress the invitation - then `password` is required. Requires role sysowner/owner/admin. Rejected on update." }, "password": { "type": "string", "format": "password", "minLength": 8, "description": "CREATE-ONLY, never returned. Admin-set password for the new account; requires `sendInvitation: false` and role sysowner/owner/admin. Must satisfy the pool password policy (min 8, upper+lower+digit+symbol). Rejected on update." }, "passwordPermanent": { "type": "boolean", "description": "CREATE-ONLY. False (default): the account lands in FORCE_CHANGE_PASSWORD and the user must change the password at first sign-in. True: the password is permanent and the account is active immediately (audited)." }, "status": { "type": "string" }, "historyEvents": { "type": "array", "items": { "title": "UserHistoryEventSchema", "type": "object", "properties": { "eventId": { "type": "string" }, "eventType": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "result": { "type": "string" }, "riskLevel": { "type": "string" }, "riskDecision": { "type": "string" }, "compromisedCredentials": { "type": "boolean" }, "challengeResponses": { "type": "array", "items": { "type": "object", "properties": { "challenge": { "type": "string" }, "result": { "type": "string" } } } }, "ipAddress": { "type": "string" }, "deviceName": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "timezone": { "type": "string" }, "newDeviceUsed": { "type": "boolean" }, "eventFeedback": { "type": "object", "properties": { "feedbackValue": { "type": "string" }, "provider": { "type": "string" } } } } } }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "UserRelationshipsSchema", "type": "object", "properties": { "role": { "title": "UserRelationshipsRoleSchema", "type": "object", "properties": { "data": { "title": "UserRelationshipsRoleDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "jobs": { "title": "UserRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "UserRelationshipsJobsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "apikeys": { "title": "UserRelationshipsApikeysSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "UserRelationshipsApikeysDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_user", "description": "Delete User", "parameters": { "type": "object", "properties": { "permanentDelete": { "type": "string", "description": "Set to true for permanent deletion (row, Cognito account and connection secrets removed). Defaults to false (soft delete: row archived + Cognito account disabled).", "enum": [ "true", "false" ] } } } } }, { "type": "function", "function": { "name": "user_options", "description": "User Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_user_roles", "description": "List User Roles", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "user_roles_options", "description": "User Roles Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_user_roles_relationship", "description": "List User Roles Relationship", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "user_roles_relationships_options", "description": "User Roles Relationships Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_user_jobs", "description": "List User Jobs", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "user_jobs_options", "description": "User Jobs Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_user_jobs_relationship", "description": "List User Jobs Relationship", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "user_jobs_relationships_options", "description": "User Jobs Relationships Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_user_apikeys", "description": "List User Apikeys", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "user_apikeys_options", "description": "User Apikeys Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_user_apikeys_relationship", "description": "List User Apikeys Relationship", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "user_apikeys_relationships_options", "description": "User Apikeys Relationships Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "create_user_upload", "description": "Create User Upload", "parameters": { "title": "CreateUserUploadRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateUserUploadRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "user-uploads" ] }, "attributes": { "type": "object", "required": [ "extension", "purpose" ], "properties": { "extension": { "type": "string", "enum": [ "png", "jpg", "jpeg", "webp" ] }, "purpose": { "type": "string", "enum": [ "avatar" ] } } } } } } } } }, { "type": "function", "function": { "name": "user_uploads_options", "description": "User Uploads Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "start_user_identity_link", "description": "Start Linking A Social Account", "parameters": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "identity-links" ] }, "attributes": { "type": "object", "required": [ "provider" ], "properties": { "provider": { "type": "string", "enum": [ "Google", "LinkedIn" ] } } } } } } } } }, { "type": "function", "function": { "name": "user_identities_options", "description": "User Identities Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "complete_user_identity_link", "description": "Complete Linking A Social Account", "parameters": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "identity-links" ] }, "attributes": { "type": "object", "required": [ "code", "state" ], "properties": { "code": { "type": "string", "description": "The authorization code the provider put in the redirect." }, "state": { "type": "string", "description": "Echoed back untouched from the redirect. It is the nonce." } } } } } } } } }, { "type": "function", "function": { "name": "user_identity_complete_options", "description": "User Identity Complete Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "delete_user_identity", "description": "Unlink A Social Account", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "user_identity_options", "description": "User Identity Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "create_user_invitation", "description": "Resend User Invitation", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "user_invitations_options", "description": "User Invitations Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_roles", "description": "List Roles", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns roles with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_role", "description": "Create Role", "parameters": { "title": "CreateRoleRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateRoleRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "roles" ] }, "attributes": { "title": "RoleAttributesSchema", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "isSystem": { "type": "boolean" }, "status": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "RoleRelationshipsSchema", "type": "object", "properties": { "users": { "title": "RoleRelationshipsUsersSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "RoleRelationshipsUsersDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "permissions": { "title": "RoleRelationshipsPermissionsSchema", "description": "Written only by the system-tenant bootstrap (sysowner roles); empty for every tenant-created role. The permission service itself is an unwired scaffold.", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "roles_options", "description": "Roles Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_role", "description": "Show Role", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_role", "description": "Update Role", "parameters": { "title": "UpdateRoleRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateRoleRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "roles" ] }, "id": { "type": "string" }, "attributes": { "title": "RoleAttributesSchema", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "isSystem": { "type": "boolean" }, "status": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_role", "description": "Delete Role", "parameters": { "type": "object", "properties": { "permanentDelete": { "type": "string", "description": "Set to true for permanent deletion (row removed). Defaults to false (soft delete: role archived).", "enum": [ "true", "false" ] } } } } }, { "type": "function", "function": { "name": "role_options", "description": "Role Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_role_users", "description": "List Role Users", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "role_users_options", "description": "Role Users Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_role_users_relationship", "description": "List Role Users Relationship", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "role_users_relationships_options", "description": "Role Users Relationships Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_apikeys", "description": "List Apikeys", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns apikeys with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_apikey", "description": "Create Apikey", "parameters": { "title": "CreateApikeyRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateApikeyRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "apikeys" ] }, "attributes": { "title": "ApikeyAttributesSchema", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "ApikeyRelationshipsSchema", "type": "object", "properties": { "users": { "title": "ApikeyRelationshipsUsersSchema", "type": "object", "properties": { "data": { "type": "array", "maxItems": 1, "description": "Exactly one entry: the key authenticates AS this single user. Kept as an array (maxItems 1) for wire compatibility - decision 2026-08-14, PLAN_RELATIONSHIP_CONTRACT.md.", "items": { "title": "ApikeyRelationshipsUsersDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "apikeys_options", "description": "Apikeys Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_apikey", "description": "Show Apikey", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_apikey", "description": "Update Apikey", "parameters": { "title": "UpdateApikeyRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateApikeyRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "apikeys" ] }, "id": { "type": "string" }, "attributes": { "title": "ApikeyAttributesSchema", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_apikey", "description": "Delete Apikey", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "apikey_options", "description": "Apikey Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_talents", "description": "List Talents", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns talents with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterShortCode": { "type": "string", "description": "Filter talents by exact shortCode value." }, "filterEmail": { "type": "string", "description": "Specifies the email address to filter the results." }, "filterPhone": { "type": "string", "description": "Filter results by exact phone number. Numbers should be in E.164 format\n(e.g. `+48123456789`). Phone-based principal lookup is the SMS channel's\nidentity check, so listing candidates / talents by phone aligns admin\nUI views with what the SMS inbound gate sees. Backed by the PhoneIndex\nGSI on each table." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_talent", "description": "Create Talent", "parameters": { "title": "CreateTalentRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateTalentRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "talents" ] }, "attributes": { "title": "TalentAttributesSchema", "type": "object", "required": [ "name", "email" ], "properties": { "status": { "type": "string", "enum": [ "active", "inactive", "pending", "archived", "failed" ] }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "secondaryEmail": { "type": "string", "format": "email" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "workEmail": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "workPhone": { "type": "string" }, "profilePictureUrl": { "type": "string" }, "availability": { "description": "Language-keyed availability criteria. Keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentAvailabilityReceivedCriteriaSchema" } }, "desiredContractLength": { "title": "TalentAttributesDesiredContractLengthSchema", "type": "object", "properties": { "duration": { "type": "string" }, "isAssumed": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "flexibility": { "type": "string" }, "reasoning": { "type": "string" } } }, "employmentType": { "title": "TalentAttributesEmploymentTypeSchema", "type": "object", "properties": { "status": { "type": "string" }, "isAssumed": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "additionalContext": { "type": "string" }, "reasoning": { "type": "string" } } }, "experienceAndSeniority": { "description": "Language-keyed experience and seniority criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "breakReason": { "type": "string" }, "quickInsights": { "description": "Language-keyed quick insights. Keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "type": "string" } }, "languagesSpoken": { "description": "Language-keyed languages spoken criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "socialLinks": { "type": "array", "items": { "title": "TalentAttributesSocialLinkSchema", "type": "object", "properties": { "platform": { "type": "string" }, "url": { "type": "string" } } } }, "desiredEmploymentType": { "type": "array", "items": { "title": "TalentAttributesDesiredEmploymentTypeSchema", "type": "object", "properties": { "type": { "type": "string" }, "isAssumed": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "reasoning": { "type": "string" } } } }, "desiredRole": { "type": "array", "items": { "title": "TalentAttributesDesiredRoleSchema", "type": "object", "properties": { "role": { "type": "string" }, "level": { "type": "string" }, "isAssumed": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "reasoning": { "type": "string" } } } }, "workPreferences": { "description": "Language-keyed work preferences criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "locationPreferences": { "description": "Language-keyed location preferences criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "workAuthorization": { "description": "Language-keyed work authorization criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "skillsAndExpertise": { "description": "Language-keyed skills and expertise criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "certifications": { "description": "Language-keyed certifications criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "licenses": { "description": "Language-keyed licenses criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "professionalExperience": { "description": "Language-keyed professional experience criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "industryExperience": { "description": "Language-keyed industry experience criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "companyTypeExperience": { "description": "Language-keyed company type experience criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "jobPositions": { "description": "Language-keyed job positions criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "jobTendencies": { "description": "Language-keyed job tendencies criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "education": { "description": "Language-keyed education criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "projectsAndAchievements": { "description": "Language-keyed projects and achievements criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "personalityAndSoftSkills": { "description": "Language-keyed personality and soft skills criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "hobbiesAndInterests": { "description": "Language-keyed hobbies and interests. Keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "references": { "description": "Language-keyed references criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "keywords": { "description": "Language-keyed keywords. Keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "performanceReviews": { "type": "array", "items": { "type": "object" } }, "personalityTests": { "type": "object", "additionalProperties": true }, "salaryExpectation": { "description": "Language-keyed salary expectation criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "relocationWillingness": { "type": "boolean" }, "requiresSponsorship": { "type": "boolean" }, "careerBreak": { "type": "boolean" }, "isTalentPool": { "type": "boolean" }, "ttl": { "type": "string" }, "alumni": { "title": "TalentAlumniSchema", "description": "Alumni/former employee information", "type": "object", "properties": { "isFormerEmployee": { "type": "boolean" }, "previousTenureMonths": { "type": "number" }, "wantsToReturn": { "type": "boolean" } } }, "referral": { "title": "TalentReferralSchema", "description": "Referral information for the talent", "type": "object", "properties": { "isReferred": { "type": "boolean" }, "referralCode": { "type": "string" }, "referrer": { "type": "object", "properties": { "email": { "type": "string" }, "fullName": { "type": "string" } } } } }, "consent": { "title": "TalentConsentSchema", "description": "GDPR/RODO consent. future = consent to be kept in the TalentPool and used for future recruitments (the TalentPool search hard-gates on it).", "type": "object", "properties": { "current": { "type": "boolean", "description": "Consent to process for the current recruitment the applicant applied to." }, "future": { "type": "boolean", "description": "Consent to be kept and used for future recruitments (TalentPool)." }, "source": { "type": "string", "description": "Where the consent was captured (e.g. apply, careerPage)." }, "timestamp": { "type": "string", "description": "ISO 8601 time the consent was recorded." } } }, "age": { "type": "string" }, "gender": { "type": "string" }, "settings": { "type": "object", "additionalProperties": true }, "shortCode": { "type": "string" }, "source": { "type": "string" }, "meta": { "type": "object", "additionalProperties": true }, "consentCurrent": { "type": "boolean", "description": "Write-only, honoured on PATCH. Consent to process for the current recruitment. Merges into `consent.current`, which is what reads return." }, "consentFuture": { "type": "boolean", "description": "Write-only, honoured on PATCH. Consent to be kept for future recruitments (TalentPool). The TalentPool search hard-gates on it, so changing this flag re-indexes the talent - set it false to honour a withdrawal." } } }, "relationships": { "title": "TalentRelationshipsSchema", "type": "object", "properties": { "candidates": { "title": "TalentRelationshipsCandidatesSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "TalentRelationshipsCandidatesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "files": { "title": "TalentRelationshipsFilesSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "TalentRelationshipsFilesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "forms": { "title": "TalentRelationshipsFormsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "TalentRelationshipsFormsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "operations": { "title": "TalentRelationshipsOperationsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "TalentRelationshipsOperationsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "tasks": { "title": "TalentRelationshipsTasksSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } }, "meta": { "type": "object", "additionalProperties": true } } } } } } }, { "type": "function", "function": { "name": "talents_options", "description": "Talents Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_talent", "description": "Show Talent", "parameters": { "type": "object", "properties": { "language": { "type": "string", "description": "Deprecated, ignored for content selection. Translated content is stored on the resource itself: translatable fields are returned as per-locale dictionaries (e.g. en-US, pl-PL) populated by the in-service AI translation pipeline.", "enum": [ "en-US", "pl-PL", "de-DE", "it-IT", "he-IL", "fr-FR", "cs-CZ" ] } } } } }, { "type": "function", "function": { "name": "update_talent", "description": "Update Talent", "parameters": { "title": "UpdateTalentRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateTalentRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "talents" ] }, "id": { "type": "string" }, "attributes": { "title": "TalentAttributesSchema", "type": "object", "required": [ "name", "email" ], "properties": { "status": { "type": "string", "enum": [ "active", "inactive", "pending", "archived", "failed" ] }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "secondaryEmail": { "type": "string", "format": "email" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "workEmail": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "workPhone": { "type": "string" }, "profilePictureUrl": { "type": "string" }, "availability": { "description": "Language-keyed availability criteria. Keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentAvailabilityReceivedCriteriaSchema" } }, "desiredContractLength": { "title": "TalentAttributesDesiredContractLengthSchema", "type": "object", "properties": { "duration": { "type": "string" }, "isAssumed": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "flexibility": { "type": "string" }, "reasoning": { "type": "string" } } }, "employmentType": { "title": "TalentAttributesEmploymentTypeSchema", "type": "object", "properties": { "status": { "type": "string" }, "isAssumed": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "additionalContext": { "type": "string" }, "reasoning": { "type": "string" } } }, "experienceAndSeniority": { "description": "Language-keyed experience and seniority criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "breakReason": { "type": "string" }, "quickInsights": { "description": "Language-keyed quick insights. Keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "type": "string" } }, "languagesSpoken": { "description": "Language-keyed languages spoken criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "socialLinks": { "type": "array", "items": { "title": "TalentAttributesSocialLinkSchema", "type": "object", "properties": { "platform": { "type": "string" }, "url": { "type": "string" } } } }, "desiredEmploymentType": { "type": "array", "items": { "title": "TalentAttributesDesiredEmploymentTypeSchema", "type": "object", "properties": { "type": { "type": "string" }, "isAssumed": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "reasoning": { "type": "string" } } } }, "desiredRole": { "type": "array", "items": { "title": "TalentAttributesDesiredRoleSchema", "type": "object", "properties": { "role": { "type": "string" }, "level": { "type": "string" }, "isAssumed": { "type": "boolean" }, "confidence": { "type": "string", "enum": [ "Low", "Medium", "High" ] }, "reasoning": { "type": "string" } } } }, "workPreferences": { "description": "Language-keyed work preferences criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "locationPreferences": { "description": "Language-keyed location preferences criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "workAuthorization": { "description": "Language-keyed work authorization criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "skillsAndExpertise": { "description": "Language-keyed skills and expertise criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "certifications": { "description": "Language-keyed certifications criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "licenses": { "description": "Language-keyed licenses criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "professionalExperience": { "description": "Language-keyed professional experience criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "industryExperience": { "description": "Language-keyed industry experience criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "companyTypeExperience": { "description": "Language-keyed company type experience criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "jobPositions": { "description": "Language-keyed job positions criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "jobTendencies": { "description": "Language-keyed job tendencies criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "education": { "description": "Language-keyed education criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "projectsAndAchievements": { "description": "Language-keyed projects and achievements criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "personalityAndSoftSkills": { "description": "Language-keyed personality and soft skills criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "hobbiesAndInterests": { "description": "Language-keyed hobbies and interests. Keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "references": { "description": "Language-keyed references criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "keywords": { "description": "Language-keyed keywords. Keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "performanceReviews": { "type": "array", "items": { "type": "object" } }, "personalityTests": { "type": "object", "additionalProperties": true }, "salaryExpectation": { "description": "Language-keyed salary expectation criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TalentReceivedCriteriaSchema" } }, "relocationWillingness": { "type": "boolean" }, "requiresSponsorship": { "type": "boolean" }, "careerBreak": { "type": "boolean" }, "isTalentPool": { "type": "boolean" }, "ttl": { "type": "string" }, "alumni": { "title": "TalentAlumniSchema", "description": "Alumni/former employee information", "type": "object", "properties": { "isFormerEmployee": { "type": "boolean" }, "previousTenureMonths": { "type": "number" }, "wantsToReturn": { "type": "boolean" } } }, "referral": { "title": "TalentReferralSchema", "description": "Referral information for the talent", "type": "object", "properties": { "isReferred": { "type": "boolean" }, "referralCode": { "type": "string" }, "referrer": { "type": "object", "properties": { "email": { "type": "string" }, "fullName": { "type": "string" } } } } }, "consent": { "title": "TalentConsentSchema", "description": "GDPR/RODO consent. future = consent to be kept in the TalentPool and used for future recruitments (the TalentPool search hard-gates on it).", "type": "object", "properties": { "current": { "type": "boolean", "description": "Consent to process for the current recruitment the applicant applied to." }, "future": { "type": "boolean", "description": "Consent to be kept and used for future recruitments (TalentPool)." }, "source": { "type": "string", "description": "Where the consent was captured (e.g. apply, careerPage)." }, "timestamp": { "type": "string", "description": "ISO 8601 time the consent was recorded." } } }, "age": { "type": "string" }, "gender": { "type": "string" }, "settings": { "type": "object", "additionalProperties": true }, "shortCode": { "type": "string" }, "source": { "type": "string" }, "meta": { "type": "object", "additionalProperties": true }, "consentCurrent": { "type": "boolean", "description": "Write-only, honoured on PATCH. Consent to process for the current recruitment. Merges into `consent.current`, which is what reads return." }, "consentFuture": { "type": "boolean", "description": "Write-only, honoured on PATCH. Consent to be kept for future recruitments (TalentPool). The TalentPool search hard-gates on it, so changing this flag re-indexes the talent - set it false to honour a withdrawal." } } } } } } } } }, { "type": "function", "function": { "name": "delete_talent", "description": "Delete Talent", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "talent_options", "description": "Talent Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_talent_candidates", "description": "List Talent Candidates", "parameters": { "type": "object", "properties": { "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "talent_candidates_options", "description": "Talent Candidates Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_talent_candidates_relationship", "description": "List Talent Candidates Relationship", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "talent_candidates_relationships_options", "description": "Talent Candidates Relationships Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_jobs", "description": "List Jobs", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns jobs with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterShortCode": { "type": "string", "description": "Filter jobs by exact shortCode value." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_job", "description": "Create Job", "parameters": { "title": "CreateJobRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateJobRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "jobs" ] }, "attributes": { "title": "JobAttributesSchema", "type": "object", "required": [ "title" ], "properties": { "title": { "title": "JobAttributesTitleSchema", "description": "The job title/position. Language-keyed object where keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "type": "string" } }, "titleInclusive": { "title": "JobAttributesTitleInclusiveSchema", "description": "The job title as shown to candidates, marked as open to every gender. Language-keyed, same keys as `title`. Read-only: it is derived from `title` by the build pipeline, not supplied by a client. `title` stays the canonical, unmarked string and is what the ATS and the search index use; this is the one public surfaces display. The shape follows the locale: Polish and Czech restate the whole phrase in the feminine because the adjectives agree with the noun, while German, French and Italian append their market marker. Surfaces with a hard length limit use a short marker instead - on Polish that is \"(K/M/NB)\", which covers MORE than the restated pair, since the pair is binary by construction. Absent on jobs created before this field existed, and on locales the pipeline declined to inflect - fall back to `title` per locale.", "type": "object", "additionalProperties": { "type": "string" } }, "description": { "title": "JobAttributesDescriptionSchema", "description": "Detailed job description. Language-keyed object.", "type": "object", "additionalProperties": { "type": "string" } }, "shortCode": { "type": "string", "description": "Unique short identifier for the job" }, "source": { "type": "string", "description": "Source of the job posting (e.g. email, erecruiter)" }, "languageCode": { "type": "string", "description": "Primary language code for the job posting (e.g. en-US, pl-PL)" }, "status": { "type": "string", "enum": [ "active", "inactive", "draft", "pending", "archived", "failed" ] }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "department": { "title": "JobAttributesDepartmentSchema", "description": "Department where the position is located. Language-keyed object.", "type": "object", "additionalProperties": { "type": "string" } }, "specialization": { "title": "JobAttributesSpecializationSchema", "description": "Job specialization area. Language-keyed object. Values are nullable - real rows carry {locale: null} before the AI fill.", "type": "object", "additionalProperties": { "type": "string", "nullable": true } }, "companyCulture": { "type": "string", "description": "Description of the company's culture and values" }, "seniority": { "type": "string", "description": "Seniority level for the role (e.g. junior, mid, senior)" }, "availability": { "title": "JobAttributesAvailabilitySchema", "description": "Availability criteria. Language-keyed object containing criteria with name, description, priority, comparisonRule and expected values.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "responsibilities": { "title": "JobAttributesResponsibilitiesSchema", "description": "List of job responsibilities. Language-keyed object where each language maps to an array of strings.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "skillsAndExpertise": { "title": "JobAttributesSkillsAndExpertiseSchema", "description": "Technical skills and domain expertise criteria. Language-keyed object containing criteria with expected skills.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "languagesSpoken": { "title": "JobAttributesLanguagesSpokenSchema", "description": "Language proficiency requirements. Language-keyed object containing criteria with expected languages.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "workPreferences": { "title": "JobAttributesWorkPreferencesSchema", "description": "Work style and schedule preferences. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "locationPreferences": { "title": "JobAttributesLocationPreferencesSchema", "description": "Geographic location requirements. Language-keyed object containing criteria with expected locations.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "industryExperience": { "title": "JobAttributesIndustryExperienceSchema", "description": "Industry sector experience requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "companyTypeExperience": { "title": "JobAttributesCompanyTypeExperienceSchema", "description": "Company type experience requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "jobPositions": { "title": "JobAttributesJobPositionsSchema", "description": "Required previous job positions. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "jobTendencies": { "title": "JobAttributesJobTendenciesSchema", "description": "Career pattern and progression requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "keywords": { "title": "JobAttributesKeywordsSchema", "description": "Relevant keywords for the position. Language-keyed object where each language maps to an array of strings.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "workAuthorization": { "title": "JobAttributesWorkAuthorizationSchema", "description": "Work authorization requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "certifications": { "title": "JobAttributesCertificationsSchema", "description": "Professional certifications requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "licenses": { "title": "JobAttributesLicensesSchema", "description": "Professional licenses requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "personalityAndSoftSkills": { "title": "JobAttributesPersonalityAndSoftSkillsSchema", "description": "Soft skills and personality trait requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "education": { "title": "JobAttributesEducationSchema", "description": "Education requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "experienceAndSeniority": { "title": "JobAttributesExperienceAndSenioritySchema", "description": "Experience and seniority level requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "benefits": { "title": "JobAttributesBenefitsSchema", "description": "Job benefits. Language-keyed object where each language maps to an array of strings.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "salaryExpectation": { "title": "JobAttributesSalaryExpectationSchema", "description": "Salary and compensation criteria. Language-keyed object containing criteria with expected salary ranges.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "locations": { "title": "JobAttributesLocationsSchema", "description": "Office locations for the job. Language-keyed object where each language maps to an array of location objects.", "type": "object", "additionalProperties": { "type": "array", "items": { "title": "JobAttributesLocationItemSchema", "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "region": { "type": "string" } } } } }, "sites": { "title": "JobAttributesSitesSchema", "description": "Work site types for the job. Language-keyed object where each language maps to an array of site objects.", "type": "object", "additionalProperties": { "type": "array", "items": { "title": "JobAttributesSiteItemSchema", "type": "object", "properties": { "siteId": { "type": "string", "nullable": true }, "siteName": { "type": "string", "nullable": true }, "siteType": { "type": "string" } } } } }, "organization": { "title": "JobAttributesOrganizationSchema", "description": "Organization details for the job", "type": "object", "properties": { "name": { "type": "string" }, "address": { "title": "JobAttributesOrganizationAddressSchema", "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "county": { "type": "string" }, "postalcode": { "type": "string" }, "street": { "type": "string" } } } } }, "settings": { "title": "JobAttributesSettingsSchema", "type": "object", "properties": { "conversation": { "title": "JobAttributesSettingsConversationSchema", "type": "object", "properties": { "email": { "title": "JobAttributesSettingsConversationEmailSchema", "type": "object", "properties": { "contact": { "title": "JobAttributesSettingsConversationEmailContactSchema", "type": "object", "properties": { "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } } } }, "delays": { "title": "JobAttributesSettingsConversationEmailDelaysSchema", "type": "object", "properties": { "initial": { "type": "string" } } }, "externalSender": { "type": "boolean" }, "isSendable": { "type": "boolean" } } }, "candidateInterview": { "title": "JobAttributesSettingsConversationCandidateInterviewSchema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "questions": { "type": "boolean" } } }, "personaInterview": { "title": "JobAttributesSettingsConversationPersonaInterviewSchema", "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "tone": { "type": "string", "description": "Conversation tone (e.g. FORMAL, INFORMAL)" } } }, "criterias": { "title": "JobAttributesSettingsCriteriasSchema", "type": "object", "properties": { "weight": { "type": "string", "description": "Overall criteria weight" }, "mandatoryCriteriaRejectionRating": { "type": "string" }, "mandatoryCriteriaSatisfyRating": { "type": "string" } } }, "operation": { "title": "JobAttributesSettingsOperationSchema", "type": "object", "properties": { "changeStage": { "type": "boolean" }, "createConversationReport": { "type": "boolean" }, "createNote": { "type": "boolean" }, "createRate": { "type": "boolean" }, "createTag": { "type": "boolean" } } }, "persona": { "title": "JobAttributesSettingsPersonaSchema", "type": "object", "properties": { "weight": { "type": "string" } } }, "ratingRestrictiveness": { "type": "string", "description": "Rating restrictiveness level (e.g. MODERATE, STRICT, LENIENT)" }, "feedback": { "title": "JobAttributesSettingsFeedbackSchema", "type": "object", "description": "Per-job switch for outbound candidate feedback. Absent = enabled. enabled=false makes feedback:resolve return enabled=false with reason disabled:job for candidates of this job, before the job override / tenant default lookup. The tenant-level switch (tenant.settings.feedback.enabled) wins over this one. Explicitly validated: enabled must be a JSON boolean.", "properties": { "enabled": { "type": "boolean" } } } } } } }, "relationships": { "title": "JobRelationshipsSchema", "type": "object", "properties": { "candidates": { "title": "JobRelationshipsCandidatesSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsCandidatesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } }, "meta": { "title": "JobRelationshipsCandidatesMetaSchema", "type": "object", "description": "Live candidate counters maintained on the job row by the candidate\nlifecycle events (created/stage-changed/deleted), clamped to >= 0.\nPresent on both list and show responses. Server-maintained: any\nvalue sent in a request body is ignored. The scalable companion to\n`GET /v1/candidates?filterJobId=` - render badges from here, rows\nfrom the list.", "properties": { "total": { "type": "integer", "description": "Number of candidates on this job." }, "byStage": { "title": "JobRelationshipsCandidatesMetaByStageSchema", "type": "object", "description": "Candidate count per v2 pipeline stage, in funnel order.\nDeprecated v1 stage values still stored on older candidate\nrows are folded into their v2 bucket by the counter\n(screened -> screening, interviewed -> interview, ...), so\nthese eight keys are the complete vocabulary. A missing key\nmeans zero. The values are designed to sum to `total`; a\npersistent mismatch means counter drift and is worth\nsurfacing, not hiding.", "properties": { "sourcing": { "type": "integer" }, "screening": { "type": "integer" }, "assessment": { "type": "integer" }, "interview": { "type": "integer" }, "offer": { "type": "integer" }, "hired": { "type": "integer" }, "onboarding": { "type": "integer" }, "evaluation": { "type": "integer" } } } } } } }, "operations": { "title": "JobRelationshipsOperationsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsOperationsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "conversations": { "title": "JobRelationshipsConversationsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsConversationsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "personas": { "title": "JobRelationshipsPersonasSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsPersonasDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "forms": { "title": "JobRelationshipsFormsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsFormsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "ads": { "title": "JobRelationshipsAdsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsAdsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "assessments": { "title": "JobRelationshipsAssessmentsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsAssessmentsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "feedbacks": { "title": "JobRelationshipsFeedbacksSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsFeedbacksDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "briefs": { "title": "JobRelationshipsBriefsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsBriefsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "users": { "title": "JobRelationshipsUsersSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsUsersDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "tasks": { "title": "JobRelationshipsTasksSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "JobRelationshipsTasksDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } }, "meta": { "type": "object", "additionalProperties": true } } } } } } }, { "type": "function", "function": { "name": "jobs_options", "description": "Jobs Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_job", "description": "Show Job", "parameters": { "type": "object", "properties": { "language": { "type": "string", "description": "Deprecated, ignored for content selection. Translated content is stored on the resource itself: translatable fields are returned as per-locale dictionaries (e.g. en-US, pl-PL) populated by the in-service AI translation pipeline.", "enum": [ "en-US", "pl-PL", "de-DE", "it-IT", "he-IL", "fr-FR", "cs-CZ" ] } } } } }, { "type": "function", "function": { "name": "update_job", "description": "Update Job", "parameters": { "title": "UpdateJobRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateJobRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "jobs" ] }, "id": { "type": "string" }, "attributes": { "title": "JobAttributesSchema", "type": "object", "required": [ "title" ], "properties": { "title": { "title": "JobAttributesTitleSchema", "description": "The job title/position. Language-keyed object where keys are locale codes (e.g. en-US, pl-PL).", "type": "object", "additionalProperties": { "type": "string" } }, "titleInclusive": { "title": "JobAttributesTitleInclusiveSchema", "description": "The job title as shown to candidates, marked as open to every gender. Language-keyed, same keys as `title`. Read-only: it is derived from `title` by the build pipeline, not supplied by a client. `title` stays the canonical, unmarked string and is what the ATS and the search index use; this is the one public surfaces display. The shape follows the locale: Polish and Czech restate the whole phrase in the feminine because the adjectives agree with the noun, while German, French and Italian append their market marker. Surfaces with a hard length limit use a short marker instead - on Polish that is \"(K/M/NB)\", which covers MORE than the restated pair, since the pair is binary by construction. Absent on jobs created before this field existed, and on locales the pipeline declined to inflect - fall back to `title` per locale.", "type": "object", "additionalProperties": { "type": "string" } }, "description": { "title": "JobAttributesDescriptionSchema", "description": "Detailed job description. Language-keyed object.", "type": "object", "additionalProperties": { "type": "string" } }, "shortCode": { "type": "string", "description": "Unique short identifier for the job" }, "source": { "type": "string", "description": "Source of the job posting (e.g. email, erecruiter)" }, "languageCode": { "type": "string", "description": "Primary language code for the job posting (e.g. en-US, pl-PL)" }, "status": { "type": "string", "enum": [ "active", "inactive", "draft", "pending", "archived", "failed" ] }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "department": { "title": "JobAttributesDepartmentSchema", "description": "Department where the position is located. Language-keyed object.", "type": "object", "additionalProperties": { "type": "string" } }, "specialization": { "title": "JobAttributesSpecializationSchema", "description": "Job specialization area. Language-keyed object. Values are nullable - real rows carry {locale: null} before the AI fill.", "type": "object", "additionalProperties": { "type": "string", "nullable": true } }, "companyCulture": { "type": "string", "description": "Description of the company's culture and values" }, "seniority": { "type": "string", "description": "Seniority level for the role (e.g. junior, mid, senior)" }, "availability": { "title": "JobAttributesAvailabilitySchema", "description": "Availability criteria. Language-keyed object containing criteria with name, description, priority, comparisonRule and expected values.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "responsibilities": { "title": "JobAttributesResponsibilitiesSchema", "description": "List of job responsibilities. Language-keyed object where each language maps to an array of strings.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "skillsAndExpertise": { "title": "JobAttributesSkillsAndExpertiseSchema", "description": "Technical skills and domain expertise criteria. Language-keyed object containing criteria with expected skills.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "languagesSpoken": { "title": "JobAttributesLanguagesSpokenSchema", "description": "Language proficiency requirements. Language-keyed object containing criteria with expected languages.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "workPreferences": { "title": "JobAttributesWorkPreferencesSchema", "description": "Work style and schedule preferences. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "locationPreferences": { "title": "JobAttributesLocationPreferencesSchema", "description": "Geographic location requirements. Language-keyed object containing criteria with expected locations.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "industryExperience": { "title": "JobAttributesIndustryExperienceSchema", "description": "Industry sector experience requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "companyTypeExperience": { "title": "JobAttributesCompanyTypeExperienceSchema", "description": "Company type experience requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "jobPositions": { "title": "JobAttributesJobPositionsSchema", "description": "Required previous job positions. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "jobTendencies": { "title": "JobAttributesJobTendenciesSchema", "description": "Career pattern and progression requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "keywords": { "title": "JobAttributesKeywordsSchema", "description": "Relevant keywords for the position. Language-keyed object where each language maps to an array of strings.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "workAuthorization": { "title": "JobAttributesWorkAuthorizationSchema", "description": "Work authorization requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "certifications": { "title": "JobAttributesCertificationsSchema", "description": "Professional certifications requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "licenses": { "title": "JobAttributesLicensesSchema", "description": "Professional licenses requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "personalityAndSoftSkills": { "title": "JobAttributesPersonalityAndSoftSkillsSchema", "description": "Soft skills and personality trait requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "education": { "title": "JobAttributesEducationSchema", "description": "Education requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "experienceAndSeniority": { "title": "JobAttributesExperienceAndSenioritySchema", "description": "Experience and seniority level requirements. Language-keyed object containing criteria.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "benefits": { "title": "JobAttributesBenefitsSchema", "description": "Job benefits. Language-keyed object where each language maps to an array of strings.", "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "salaryExpectation": { "title": "JobAttributesSalaryExpectationSchema", "description": "Salary and compensation criteria. Language-keyed object containing criteria with expected salary ranges.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/JobCriteriaSchema" } }, "locations": { "title": "JobAttributesLocationsSchema", "description": "Office locations for the job. Language-keyed object where each language maps to an array of location objects.", "type": "object", "additionalProperties": { "type": "array", "items": { "title": "JobAttributesLocationItemSchema", "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "region": { "type": "string" } } } } }, "sites": { "title": "JobAttributesSitesSchema", "description": "Work site types for the job. Language-keyed object where each language maps to an array of site objects.", "type": "object", "additionalProperties": { "type": "array", "items": { "title": "JobAttributesSiteItemSchema", "type": "object", "properties": { "siteId": { "type": "string", "nullable": true }, "siteName": { "type": "string", "nullable": true }, "siteType": { "type": "string" } } } } }, "organization": { "title": "JobAttributesOrganizationSchema", "description": "Organization details for the job", "type": "object", "properties": { "name": { "type": "string" }, "address": { "title": "JobAttributesOrganizationAddressSchema", "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "county": { "type": "string" }, "postalcode": { "type": "string" }, "street": { "type": "string" } } } } }, "settings": { "title": "JobAttributesSettingsSchema", "type": "object", "properties": { "conversation": { "title": "JobAttributesSettingsConversationSchema", "type": "object", "properties": { "email": { "title": "JobAttributesSettingsConversationEmailSchema", "type": "object", "properties": { "contact": { "title": "JobAttributesSettingsConversationEmailContactSchema", "type": "object", "properties": { "cc": { "type": "array", "items": { "type": "string" } }, "bcc": { "type": "array", "items": { "type": "string" } } } }, "delays": { "title": "JobAttributesSettingsConversationEmailDelaysSchema", "type": "object", "properties": { "initial": { "type": "string" } } }, "externalSender": { "type": "boolean" }, "isSendable": { "type": "boolean" } } }, "candidateInterview": { "title": "JobAttributesSettingsConversationCandidateInterviewSchema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "questions": { "type": "boolean" } } }, "personaInterview": { "title": "JobAttributesSettingsConversationPersonaInterviewSchema", "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "tone": { "type": "string", "description": "Conversation tone (e.g. FORMAL, INFORMAL)" } } }, "criterias": { "title": "JobAttributesSettingsCriteriasSchema", "type": "object", "properties": { "weight": { "type": "string", "description": "Overall criteria weight" }, "mandatoryCriteriaRejectionRating": { "type": "string" }, "mandatoryCriteriaSatisfyRating": { "type": "string" } } }, "operation": { "title": "JobAttributesSettingsOperationSchema", "type": "object", "properties": { "changeStage": { "type": "boolean" }, "createConversationReport": { "type": "boolean" }, "createNote": { "type": "boolean" }, "createRate": { "type": "boolean" }, "createTag": { "type": "boolean" } } }, "persona": { "title": "JobAttributesSettingsPersonaSchema", "type": "object", "properties": { "weight": { "type": "string" } } }, "ratingRestrictiveness": { "type": "string", "description": "Rating restrictiveness level (e.g. MODERATE, STRICT, LENIENT)" }, "feedback": { "title": "JobAttributesSettingsFeedbackSchema", "type": "object", "description": "Per-job switch for outbound candidate feedback. Absent = enabled. enabled=false makes feedback:resolve return enabled=false with reason disabled:job for candidates of this job, before the job override / tenant default lookup. The tenant-level switch (tenant.settings.feedback.enabled) wins over this one. Explicitly validated: enabled must be a JSON boolean.", "properties": { "enabled": { "type": "boolean" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_job", "description": "Delete Job", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "job_options", "description": "Job Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_job_candidates", "description": "List Job Candidates", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "job_candidates_options", "description": "Job Candidates Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_job_candidates_relationship", "description": "List Job Candidates Relationship", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "job_candidates_relationships_options", "description": "Job Candidates Relationships Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_candidates", "description": "List Candidates", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns candidates with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterShortCode": { "type": "string", "description": "Filter candidates by exact shortCode value." }, "filterJobId": { "type": "string", "description": "Returns candidates applied to the given job (JobIndex lookup). The scalable way to list a job's pipeline." }, "filterTalentId": { "type": "string", "description": "Returns candidates belonging to the given talent (TalentIndex lookup). The scalable way to list one person's applications across jobs; combine with nothing (one filter per request)." }, "filterEmail": { "type": "string", "description": "Specifies the email address to filter the results." }, "filterPhone": { "type": "string", "description": "Filter results by exact phone number. Numbers should be in E.164 format\n(e.g. `+48123456789`). Phone-based principal lookup is the SMS channel's\nidentity check, so listing candidates / talents by phone aligns admin\nUI views with what the SMS inbound gate sees. Backed by the PhoneIndex\nGSI on each table." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_candidate", "description": "Create Candidate", "parameters": { "title": "CreateCandidateRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateCandidateRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "candidates" ] }, "attributes": { "title": "CandidateAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the candidate. Required on create." }, "email": { "type": "string", "description": "Primary email address" }, "secondaryEmail": { "type": "string", "description": "Secondary email address" }, "workEmail": { "type": "string", "description": "Work email address" }, "phone": { "type": "string", "description": "Primary phone number" }, "workPhone": { "type": "string", "description": "Work phone number" }, "status": { "type": "string", "description": "Current status of the candidate", "enum": [ "active", "paused", "withdrawn", "rejected", "hired", "archived", "inactive", "onHold", "offerExtended", "offerDeclined", "futureConsideration" ] }, "stage": { "type": "string", "description": "Current stage in the recruitment pipeline", "enum": [ "sourcing", "screening", "assessment", "interview", "offer", "hired", "onboarding", "evaluation", "sourced", "applied", "initial", "prescreened", "screened", "assessed", "contacted", "interviewed", "offered", "onboarded", "evaluated" ] }, "age": { "type": "string", "description": "Candidate age" }, "gender": { "type": "string", "description": "Candidate gender" }, "source": { "type": "string", "description": "Where the candidate originated (e.g., careerPage, jobBoard, linkedin, talentPool)" }, "channel": { "type": "string", "description": "How the candidate entered the system", "enum": [ "form", "email", "call", "chat", "api", "agent" ] }, "shortCode": { "type": "string", "description": "Short code identifier for the candidate" }, "languageCode": { "type": "string", "description": "Preferred language code (e.g., en-US, pl-PL)" }, "profilePictureUrl": { "type": "string", "description": "Public CDN URL of the applicant's photo, snapshotted ONCE from talent.profilePictureUrl when the candidature is created (the CV photo the applicant sent for this application). Read-only here - the talent is the source of truth and later talent photo changes do not propagate. Null when the CV carried no usable portrait or the talent has no future-recruitment consent." }, "recommendationStatusCode": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Numeric recommendation status code" }, "overallMatchRating": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Overall match rating (0-5). Persisted as a string in DDB on\nlegacy data and as an integer on newer rows; the oneOf\naccepts both shapes so the SDK doesn't fail validation when\ndeserialising mixed-vintage candidates." }, "prevOverallMatchRating": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Previous overall match rating before recalculation. Same\nint/string ambivalence as overallMatchRating - oneOf\naccepts both." }, "ttl": { "type": "string", "description": "Time-to-live expiration timestamp" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "alumni": { "title": "TalentAlumniSchema", "description": "Alumni/former employee information", "type": "object", "properties": { "isFormerEmployee": { "type": "boolean" }, "previousTenureMonths": { "type": "number" }, "wantsToReturn": { "type": "boolean" } } }, "referral": { "title": "TalentReferralSchema", "description": "Referral information for the talent", "type": "object", "properties": { "isReferred": { "type": "boolean" }, "referralCode": { "type": "string" }, "referrer": { "type": "object", "properties": { "email": { "type": "string" }, "fullName": { "type": "string" } } } } }, "jobPositionTitle": { "type": "object", "description": "Language-keyed job position title", "additionalProperties": { "type": "string" } }, "rejectionTicket": { "type": "object", "description": "Language-keyed rejection ticket. Pre-AI: empty string per\nlocale. Post-AI: object with isAssumed / description /\nstatus / category / etc keys. Locale value type is\nintentionally unconstrained (Any) - see comment above.", "additionalProperties": true }, "recommendationStatus": { "type": "object", "description": "Language-keyed recommendation status. Pre-AI: empty string.\nPost-AI: typically scalar string (\"Recommended\", \"Not\nRecommended\", ...). Locale value type unconstrained (Any).", "additionalProperties": true }, "overallAssessment": { "type": "object", "description": "Language-keyed overall assessment. Pre-AI: empty string.\nPost-AI: long-form scalar string per locale. Locale value\ntype unconstrained (Any).", "additionalProperties": true }, "nextSteps": { "type": "object", "description": "Language-keyed next-steps recommendations. Pre-AI: empty\nstring. Post-AI: array of strings per locale. Locale value\ntype unconstrained (Any).", "additionalProperties": true }, "insightsAndAnalysis": { "type": "object", "description": "Language-keyed insights and analysis. Pre-AI: empty string.\nPost-AI: free-form object per locale. Locale value type\nunconstrained (Any).", "additionalProperties": true }, "keywords": { "type": "object", "description": "Language-keyed extracted keywords. Pre-AI: empty string.\nPost-AI: array of strings per locale. Locale value type\nunconstrained (Any).", "additionalProperties": true }, "availability": { "type": "object", "description": "Language-keyed availability criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "certifications": { "type": "object", "description": "Language-keyed certifications criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "companyTypeExperience": { "type": "object", "description": "Language-keyed company type experience criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "education": { "type": "object", "description": "Language-keyed education criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "experienceAndSeniority": { "type": "object", "description": "Language-keyed experience and seniority criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "industryExperience": { "type": "object", "description": "Language-keyed industry experience criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "jobPositions": { "type": "object", "description": "Language-keyed job positions criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "jobTendencies": { "type": "object", "description": "Language-keyed job tendencies criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "languagesSpoken": { "type": "object", "description": "Language-keyed languages spoken criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "licenses": { "type": "object", "description": "Language-keyed licenses criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "locationPreferences": { "type": "object", "description": "Language-keyed location preferences criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "personalityAndSoftSkills": { "type": "object", "description": "Language-keyed personality and soft skills criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "salaryExpectation": { "type": "object", "description": "Language-keyed salary expectation criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "skillsAndExpertise": { "type": "object", "description": "Language-keyed skills and expertise criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "workAuthorization": { "type": "object", "description": "Language-keyed work authorization criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "workPreferences": { "type": "object", "description": "Language-keyed work preferences criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "meta": { "type": "object", "additionalProperties": true } } }, "relationships": { "title": "CandidateRelationshipsSchema", "type": "object", "properties": { "job": { "title": "CandidateRelationshipsJobSchema", "type": "object", "properties": { "data": { "title": "CandidateRelationshipsJobDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "talent": { "title": "CandidateRelationshipsTalentSchema", "type": "object", "properties": { "data": { "title": "CandidateRelationshipsTalentDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "files": { "title": "CandidateRelationshipsFilesSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "CandidateRelationshipsFilesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "forms": { "title": "CandidateRelationshipsFormsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "CandidateRelationshipsFormsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "operations": { "title": "CandidateRelationshipsOperationsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "CandidateRelationshipsOperationsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "tasks": { "title": "CandidateRelationshipsTasksSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } }, "meta": { "type": "object", "additionalProperties": true } } } } } } }, { "type": "function", "function": { "name": "candidates_options", "description": "Candidates Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_candidate", "description": "Show Candidate", "parameters": { "type": "object", "properties": { "language": { "type": "string", "description": "Deprecated, ignored for content selection. Translated content is stored on the resource itself: translatable fields are returned as per-locale dictionaries (e.g. en-US, pl-PL) populated by the in-service AI translation pipeline.", "enum": [ "en-US", "pl-PL", "de-DE", "it-IT", "he-IL", "fr-FR", "cs-CZ" ] } } } } }, { "type": "function", "function": { "name": "update_candidate", "description": "Update Candidate", "parameters": { "title": "UpdateCandidateRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateCandidateRequestBodyData", "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "candidates" ] }, "id": { "type": "string" }, "attributes": { "title": "CandidateAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Full name of the candidate. Required on create." }, "email": { "type": "string", "description": "Primary email address" }, "secondaryEmail": { "type": "string", "description": "Secondary email address" }, "workEmail": { "type": "string", "description": "Work email address" }, "phone": { "type": "string", "description": "Primary phone number" }, "workPhone": { "type": "string", "description": "Work phone number" }, "status": { "type": "string", "description": "Current status of the candidate", "enum": [ "active", "paused", "withdrawn", "rejected", "hired", "archived", "inactive", "onHold", "offerExtended", "offerDeclined", "futureConsideration" ] }, "stage": { "type": "string", "description": "Current stage in the recruitment pipeline", "enum": [ "sourcing", "screening", "assessment", "interview", "offer", "hired", "onboarding", "evaluation", "sourced", "applied", "initial", "prescreened", "screened", "assessed", "contacted", "interviewed", "offered", "onboarded", "evaluated" ] }, "age": { "type": "string", "description": "Candidate age" }, "gender": { "type": "string", "description": "Candidate gender" }, "source": { "type": "string", "description": "Where the candidate originated (e.g., careerPage, jobBoard, linkedin, talentPool)" }, "channel": { "type": "string", "description": "How the candidate entered the system", "enum": [ "form", "email", "call", "chat", "api", "agent" ] }, "shortCode": { "type": "string", "description": "Short code identifier for the candidate" }, "languageCode": { "type": "string", "description": "Preferred language code (e.g., en-US, pl-PL)" }, "profilePictureUrl": { "type": "string", "description": "Public CDN URL of the applicant's photo, snapshotted ONCE from talent.profilePictureUrl when the candidature is created (the CV photo the applicant sent for this application). Read-only here - the talent is the source of truth and later talent photo changes do not propagate. Null when the CV carried no usable portrait or the talent has no future-recruitment consent." }, "recommendationStatusCode": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Numeric recommendation status code" }, "overallMatchRating": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Overall match rating (0-5). Persisted as a string in DDB on\nlegacy data and as an integer on newer rows; the oneOf\naccepts both shapes so the SDK doesn't fail validation when\ndeserialising mixed-vintage candidates." }, "prevOverallMatchRating": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Previous overall match rating before recalculation. Same\nint/string ambivalence as overallMatchRating - oneOf\naccepts both." }, "ttl": { "type": "string", "description": "Time-to-live expiration timestamp" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "alumni": { "title": "TalentAlumniSchema", "description": "Alumni/former employee information", "type": "object", "properties": { "isFormerEmployee": { "type": "boolean" }, "previousTenureMonths": { "type": "number" }, "wantsToReturn": { "type": "boolean" } } }, "referral": { "title": "TalentReferralSchema", "description": "Referral information for the talent", "type": "object", "properties": { "isReferred": { "type": "boolean" }, "referralCode": { "type": "string" }, "referrer": { "type": "object", "properties": { "email": { "type": "string" }, "fullName": { "type": "string" } } } } }, "jobPositionTitle": { "type": "object", "description": "Language-keyed job position title", "additionalProperties": { "type": "string" } }, "rejectionTicket": { "type": "object", "description": "Language-keyed rejection ticket. Pre-AI: empty string per\nlocale. Post-AI: object with isAssumed / description /\nstatus / category / etc keys. Locale value type is\nintentionally unconstrained (Any) - see comment above.", "additionalProperties": true }, "recommendationStatus": { "type": "object", "description": "Language-keyed recommendation status. Pre-AI: empty string.\nPost-AI: typically scalar string (\"Recommended\", \"Not\nRecommended\", ...). Locale value type unconstrained (Any).", "additionalProperties": true }, "overallAssessment": { "type": "object", "description": "Language-keyed overall assessment. Pre-AI: empty string.\nPost-AI: long-form scalar string per locale. Locale value\ntype unconstrained (Any).", "additionalProperties": true }, "nextSteps": { "type": "object", "description": "Language-keyed next-steps recommendations. Pre-AI: empty\nstring. Post-AI: array of strings per locale. Locale value\ntype unconstrained (Any).", "additionalProperties": true }, "insightsAndAnalysis": { "type": "object", "description": "Language-keyed insights and analysis. Pre-AI: empty string.\nPost-AI: free-form object per locale. Locale value type\nunconstrained (Any).", "additionalProperties": true }, "keywords": { "type": "object", "description": "Language-keyed extracted keywords. Pre-AI: empty string.\nPost-AI: array of strings per locale. Locale value type\nunconstrained (Any).", "additionalProperties": true }, "availability": { "type": "object", "description": "Language-keyed availability criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "certifications": { "type": "object", "description": "Language-keyed certifications criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "companyTypeExperience": { "type": "object", "description": "Language-keyed company type experience criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "education": { "type": "object", "description": "Language-keyed education criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "experienceAndSeniority": { "type": "object", "description": "Language-keyed experience and seniority criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "industryExperience": { "type": "object", "description": "Language-keyed industry experience criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "jobPositions": { "type": "object", "description": "Language-keyed job positions criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "jobTendencies": { "type": "object", "description": "Language-keyed job tendencies criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "languagesSpoken": { "type": "object", "description": "Language-keyed languages spoken criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "licenses": { "type": "object", "description": "Language-keyed licenses criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "locationPreferences": { "type": "object", "description": "Language-keyed location preferences criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "personalityAndSoftSkills": { "type": "object", "description": "Language-keyed personality and soft skills criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "salaryExpectation": { "type": "object", "description": "Language-keyed salary expectation criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "skillsAndExpertise": { "type": "object", "description": "Language-keyed skills and expertise criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "workAuthorization": { "type": "object", "description": "Language-keyed work authorization criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "workPreferences": { "type": "object", "description": "Language-keyed work preferences criteria", "additionalProperties": { "$ref": "#/components/schemas/CandidateCriteriaSchema" } }, "meta": { "type": "object", "additionalProperties": true } } }, "relationships": { "title": "CandidateRelationshipsSchema", "type": "object", "properties": { "job": { "title": "CandidateRelationshipsJobSchema", "type": "object", "properties": { "data": { "title": "CandidateRelationshipsJobDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "talent": { "title": "CandidateRelationshipsTalentSchema", "type": "object", "properties": { "data": { "title": "CandidateRelationshipsTalentDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "files": { "title": "CandidateRelationshipsFilesSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "CandidateRelationshipsFilesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "forms": { "title": "CandidateRelationshipsFormsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "CandidateRelationshipsFormsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "operations": { "title": "CandidateRelationshipsOperationsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "CandidateRelationshipsOperationsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "tasks": { "title": "CandidateRelationshipsTasksSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_candidate", "description": "Delete Candidate", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "candidate_options", "description": "Candidate Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_candidate_jobs", "description": "List Candidate Jobs", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "candidate_jobs_options", "description": "Candidate Jobs Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_candidate_jobs_relationship", "description": "List Candidate Jobs Relationship", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "candidate_jobs_relationships_options", "description": "Candidate Jobs Relationships Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_candidate_talents", "description": "List Candidate Talents", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "candidate_talents_options", "description": "Candidate Talents Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_candidate_talents_relationship", "description": "List Candidate Talents Relationship", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "candidate_talents_relationships_options", "description": "Candidate Talents Relationships Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_files", "description": "List Files", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns files with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_file", "description": "Create File", "parameters": { "title": "CreateFileRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateFileRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "files" ] }, "attributes": { "title": "FileAttributesSchema", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "extension": { "type": "string" }, "shortCode": { "type": "string" }, "source": { "type": "string" }, "action": { "type": "string" }, "type": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "pdf", "video", "audio", "text", "unknown" ], "description": "Renderer hint derived from contentType + conversion outputs.\nSet by the file service after conversion. `unknown` for\ncontent types with no preview pipeline." }, "detectedLanguage": { "type": "string", "description": "BCP-47 code for the source content's primary language,\ndetected during AI extraction. Transcript language for\nvideo/audio, document body language for PDF/image.\nStable per-file. Drives the translation pipeline:\nAI extraction outputs canonical en-US, then the file AI\nLambda translates `summary` (and any future fields in\nFile.TRANSLATION_FIELDS) into the tenant's target locale.\nSource content (transcript / rawText) stays verbatim in\nthis language - we only translate AI-derived synthesis text." }, "sizeBytes": { "type": "integer", "description": "File size in bytes. Stable post-upload." }, "durationSeconds": { "type": "number", "description": "Duration of media files (video/audio) in seconds. Set by ffmpeg conversion. Null for non-media." }, "pages": { "type": "array", "description": "Per-page metadata for paginated content (PDFs converted to\nPNGs by Poppler, multi-page images). Stable structure ONLY -\ndimensions, no content. The presigned URL for each page\nrender lives at `meta.previewUrls.pages[i]`, indexed by the\nsame position. Per-page text content lives in the result\nJSON pointed at by `meta.resultRef`. Null for non-paginated\ncontent.", "items": { "type": "object", "properties": { "page": { "type": "integer", "description": "1-indexed page number." }, "width": { "type": "integer", "description": "Pixel width of the rendered page image." }, "height": { "type": "integer", "description": "Pixel height of the rendered page image." } } } }, "summary": { "type": "object", "additionalProperties": true, "description": "Multilingual AI-generated summary, locale-keyed (e.g.\n{\"en-US\": \"...\", \"pl-PL\": \"...\"}). Bounded by design (~1-2\nparagraphs, ~500 bytes per locale) so it fits cleanly on\nthe row and works in scan UIs / list views without an\nextra fetch. Full transcript / raw OCR / per-page text are\nNOT here - they live in the result JSON pointed at by\n`meta.resultRef`." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "FileRelationshipsSchema", "type": "object", "properties": { "links": { "title": "FileRelationshipsLinksSchema", "description": "URLs found inside this file's content (e.g. a portfolio/LinkedIn URL in a CV), each fetched to markdown (Crawl4AI Link). To-many; container-owns-links. (Was to-one from the dead file<-screenshot<-link era; link and file are now independent.)", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "FileRelationshipsLinksDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "talents": { "title": "FileRelationshipsTalentsSchema", "description": "Talents this file belongs to (e.g. an ATS-imported CV). Set at create by workflow actions (file:process relationships input).", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "FileRelationshipsTalentsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "candidates": { "title": "FileRelationshipsCandidatesSchema", "description": "Candidates (applications) this file belongs to. Set at create by workflow actions (file:process relationships input).", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "FileRelationshipsCandidatesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } }, "meta": { "title": "ResourceMetaSchema", "type": "object", "additionalProperties": true } } } } } } }, { "type": "function", "function": { "name": "files_options", "description": "Files Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_file", "description": "Show File", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_file", "description": "Update File", "parameters": { "title": "UpdateFileRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateFileRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "files" ] }, "id": { "type": "string" }, "attributes": { "title": "FileAttributesSchema", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "extension": { "type": "string" }, "shortCode": { "type": "string" }, "source": { "type": "string" }, "action": { "type": "string" }, "type": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "pdf", "video", "audio", "text", "unknown" ], "description": "Renderer hint derived from contentType + conversion outputs.\nSet by the file service after conversion. `unknown` for\ncontent types with no preview pipeline." }, "detectedLanguage": { "type": "string", "description": "BCP-47 code for the source content's primary language,\ndetected during AI extraction. Transcript language for\nvideo/audio, document body language for PDF/image.\nStable per-file. Drives the translation pipeline:\nAI extraction outputs canonical en-US, then the file AI\nLambda translates `summary` (and any future fields in\nFile.TRANSLATION_FIELDS) into the tenant's target locale.\nSource content (transcript / rawText) stays verbatim in\nthis language - we only translate AI-derived synthesis text." }, "sizeBytes": { "type": "integer", "description": "File size in bytes. Stable post-upload." }, "durationSeconds": { "type": "number", "description": "Duration of media files (video/audio) in seconds. Set by ffmpeg conversion. Null for non-media." }, "pages": { "type": "array", "description": "Per-page metadata for paginated content (PDFs converted to\nPNGs by Poppler, multi-page images). Stable structure ONLY -\ndimensions, no content. The presigned URL for each page\nrender lives at `meta.previewUrls.pages[i]`, indexed by the\nsame position. Per-page text content lives in the result\nJSON pointed at by `meta.resultRef`. Null for non-paginated\ncontent.", "items": { "type": "object", "properties": { "page": { "type": "integer", "description": "1-indexed page number." }, "width": { "type": "integer", "description": "Pixel width of the rendered page image." }, "height": { "type": "integer", "description": "Pixel height of the rendered page image." } } } }, "summary": { "type": "object", "additionalProperties": true, "description": "Multilingual AI-generated summary, locale-keyed (e.g.\n{\"en-US\": \"...\", \"pl-PL\": \"...\"}). Bounded by design (~1-2\nparagraphs, ~500 bytes per locale) so it fits cleanly on\nthe row and works in scan UIs / list views without an\nextra fetch. Full transcript / raw OCR / per-page text are\nNOT here - they live in the result JSON pointed at by\n`meta.resultRef`." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_file", "description": "Delete File", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "file_options", "description": "File Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_links", "description": "List Links", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns links with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_link", "description": "Create Link", "parameters": { "title": "CreateLinkRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateLinkRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "links" ] }, "attributes": { "type": "object", "required": [ "sourceUrl" ], "properties": { "sourceUrl": { "type": "string", "description": "The URL to fetch and render to markdown." } } } } } } } } }, { "type": "function", "function": { "name": "links_options", "description": "Links Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_link", "description": "Show Link", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "refresh_link", "description": "Re-fetch Link", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "delete_link", "description": "Delete Link", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "link_options", "description": "Link Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_emails", "description": "List Emails", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Filter by the email's lifecycle status. Omit to return all statuses.", "enum": [ "draft", "scheduled", "sent", "suppressed", "archived", "trashed", "failed", "pending" ] }, "filterConversationId": { "type": "string", "description": "Return only emails belonging to this conversation. Resolved via the ConversationIdIndex GSI (top-level denormalisation of relationships.conversations[0].data.id). Pass the full conversation id (e.g. `980434e7...-2`)." }, "filterDirection": { "type": "string", "description": "Return only emails with this direction. `inbound` = received from an external sender (Inbox), `outbound` = composed by the tenant (Sent). Resolved via the DirectionIndex GSI. Mutually exclusive with `filterStatus` and `filterConversationId` at the pagination layer.", "enum": [ "inbound", "outbound" ] }, "filterIds": { "type": "string", "description": "Batch-fetch emails by id. Pass a comma-separated list (e.g. `abc-1,def-2,ghi-3`). Resolves each id's shard from its suffix and issues a BatchGetItem. Used by the inbox UI to hydrate emails referenced by state rows (folder=unseen / starred / spam) without N showEmail calls. Cap: 500 ids per request; beyond that, page the state list and batch again. Bypasses pagination - the returned `data` is the full batch result with no `nextPage` cursor." }, "filterIsSystemSpam": { "type": "boolean", "description": "Return only emails the system (broker / classifier) flagged as spam. Used by the Spam folder's `isSystemSpam=true` leg - the other leg comes from `/v1/states?folder=spam`. Backed by a filter-expression scan across shards for v1; promote to a sparse `SystemSpamIndex` if load warrants. Mutually exclusive with the other index-backed filters at the pagination layer." }, "sort": { "type": "string", "description": "Order results by a time field. Leading `-` means descending\n(newest-first). Accepted values:\n `-created` newest-first by creation time (CreatedIndex)\n `created` oldest-first by creation time\n `-modified` most-recently-modified first (ModifiedIndex)\n `modified` least-recently-modified first\nTakes effect only when no equality filter (filterStatus,\nfilterConversationId, filterDirection) dictates a different\nindex; equality filters win. Compatible with date-range filters\n(filterCreatedFrom/To, filterModifiedFrom/To) which already use\nthe same indexes; sort just picks the direction.", "enum": [ "-created", "created", "-modified", "modified" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_email", "description": "Create Email", "parameters": { "title": "CreateEmailRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateEmailRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "emails" ] }, "attributes": { "title": "EmailAttributesSchema", "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sent", "received", "suppressed", "archived", "trashed", "failed", "pending" ], "description": "Lifecycle status. draft = composing, scheduled = workflow owns the send, sent = outbound delivered to SES, received = inbound accepted by broker (replaces the legacy `sent` value used for inbound), suppressed = SES bounce/complaint, archived = user explicitly archived (kept indefinitely, hidden from inbox view), trashed = user moved to Trash bin (default soft DELETE; recoverable, candidate for periodic permanent purge), failed = internal error, pending = transitional." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Whether the email was received from an external sender (inbound, populated by the broker) or composed by the tenant/system and sent out (outbound). Populated at create time; never changes." }, "emailFrom": { "type": "string" }, "emailTo": { "type": "string" }, "emailCc": { "type": "array", "items": { "type": "string" }, "description": "CC recipients. Each entry is an RFC 5322 address string." }, "emailBcc": { "type": "array", "items": { "type": "string" }, "description": "BCC recipients. Each entry is an RFC 5322 address string." }, "subject": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Multilingual subject keyed by IETF BCP 47 locale code (e.g. `en-US`, `pl-PL`). The DAL writes per-locale entries from the AI analyze + translate steps; the UI picks the right key based on `conversationLanguageCode`." }, "body": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Multilingual HTML body keyed by IETF BCP 47 locale code. Same shape as `subject`. Body values are HTML strings; plain-text fallback is derived on send." }, "shortCode": { "type": "string" }, "source": { "type": "string" }, "isReply": { "type": "boolean" }, "isSendable": { "type": "boolean" }, "isExternalSender": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "fileName": { "type": "string", "description": "Display name shown in the mail client and used as the attachment filename on send." }, "url": { "type": "string", "description": "S3 URL of the stored file. For user-uploaded attachments this is the path returned by POST /v1/files; for system-generated attachments (job/persona/report PDFs) it is the resource's own S3 path." }, "type": { "type": "string", "description": "Resource type this attachment belongs to. User-uploaded attachments use `files`; system-generated attachments use the owning resource type: `jobs`, `personas`, `talents`, `candidates`, `reports`, `ads`." }, "fileId": { "type": "string", "description": "When `type == \"files\"`, the file resource ID so the frontend can resolve the latest file metadata (status, processing state) without parsing the URL." }, "size": { "type": "integer", "description": "File size in bytes. Frontend displays it in the compose preview and mail list. Set by the upload flow from the Content-Length of the S3 object; absent on legacy rows." }, "contentType": { "type": "string", "description": "MIME type (e.g. `application/pdf`, `image/png`). Drives icon selection in the UI and the Content-Type header in the outbound MIME part. Absent on legacy rows; frontend should fall back to extension inference." }, "thumbnailUrl": { "type": "string", "description": "Optional S3 URL of a PNG preview (first-page render for PDFs/DOCX). Populated by the file service's conversion pipeline when a preview is available. Absent for non-previewable types." } } }, "description": "Attachments on the email. For user-uploaded attachments: frontend creates a File via POST /v1/files (which returns a presigned PUT URL), uploads to S3, then references the File here with `type: \"files\"` and the returned `url`/`fileId`. For system-generated attachments (job/persona/report PDFs) the eventbus / outbound path populates these automatically." }, "conversationLanguageCode": { "type": "string", "description": "Denormalised copy of the related conversation's languageCode (e.g. `pl-PL`, `en-US`). Avoids an N+1 fetch when the list/detail view needs to pick the right locale for the multilingual subject/body dicts. Source of truth is the conversation row; read-only from the email's perspective." }, "parentEmailId": { "type": "string", "description": "Application-layer pointer to the email this one replies to. Used by the UI to render an 'in reply to' link in thread views. Set by the compose flow (frontend passes the parent on Reply) and by the broker when an inbound email matches an outbound via RFC 5322 In-Reply-To. Separate from meta.reference which carries the raw SMTP header chain." }, "fromUserId": { "type": "string", "description": "Denormalised user id of the sender for outbound emails (the boe workflow user, or the human composer). Frontend joins this against its local user cache to render avatar + display name without a per-row API call. Null on inbound mail." }, "fromCandidateId": { "type": "string", "description": "Denormalised candidate id of the sender for inbound replies from a candidate in an active conversation. Frontend joins this against its local candidate cache to render initials and the candidate name. Null on outbound mail and on anonymous inbound that didn't match a candidate." }, "isSystemSpam": { "type": "boolean", "description": "System-level spam verdict on this email. Set by the broker (or a future classifier) at inbound time; never reflects a single user's opinion. Distinct from `status=suppressed`, which is SES reporting we cannot deliver on OUTBOUND. Frontend's Spam folder unions (my states where isSpam=true) with (emails where isSystemSpam=true)." }, "scheduleId": { "type": "string", "description": "Foreign key to the Schedule resource driving this email's send. Populated by the wait:process workflow action right after it creates the Schedule. Null when no delayed send is pending (drafts, already-sent rows, inbound mail). To cancel the scheduled send, call DELETE /v1/schedules/{scheduleId} - the email eventbus handler listens for SCHEDULE_CANCELLED and reverts the row back to draft automatically." }, "scheduledFireAt": { "type": "string", "description": "Denormalised copy of the owning Schedule's `fireAt` timestamp (ISO 8601). The scheduled-send banner reads this directly so the UI never has to round-trip to /v1/schedules just to render 'Send scheduled for X'. Source of truth is the Schedule; this field stays stable because Schedule.fireAt is immutable post-create." }, "ttl": { "type": "string" }, "sendScheduleDate": { "type": "string", "deprecated": true, "description": "Legacy field from the retired CRUD-scheduler path. Kept as read-only metadata on old rows. New emails do not populate it; scheduling is owned by the workflow engine's wait:process action via the Schedule resource." }, "meta": { "type": "object", "additionalProperties": true }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "EmailRelationshipsSchema", "type": "object", "properties": { "files": { "title": "EmailRelationshipsFilesSchema", "description": "File attachments on this email (File entities). To-many; container-owns-files.", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "EmailRelationshipsFilesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "links": { "title": "EmailRelationshipsLinksSchema", "description": "URLs shared in this email, each fetched to markdown (Crawl4AI Link). To-many; container-owns-links.", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "EmailRelationshipsLinksDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "candidate": { "title": "EmailRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "title": "EmailRelationshipsCandidateDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "conversations": { "title": "EmailRelationshipsConversationsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "EmailRelationshipsConversationsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "report": { "title": "EmailRelationshipsReportSchema", "type": "object", "properties": { "data": { "title": "EmailRelationshipsReportDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "operation": { "title": "EmailRelationshipsOperationSchema", "type": "object", "properties": { "data": { "title": "EmailRelationshipsOperationDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "schedule": { "title": "EmailRelationshipsScheduleSchema", "type": "object", "description": "The Schedule arming this email's delayed send. Denormalised mirror of scheduleId so clients can `?include=schedule` in a single request. Populated by the email eventbus handler reacting to SCHEDULE_CREATED. Null while the email is draft / already-sent / inbound.", "properties": { "data": { "title": "EmailRelationshipsScheduleDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "users": { "title": "EmailRelationshipsUsersSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "jobs": { "title": "EmailRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "assessments": { "title": "EmailRelationshipsAssessmentsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "ads": { "title": "EmailRelationshipsAdsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } }, "meta": { "type": "object", "additionalProperties": true } } } } } } }, { "type": "function", "function": { "name": "emails_options", "description": "Emails Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_email", "description": "Show Email", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_email", "description": "Update Email", "parameters": { "title": "UpdateEmailRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateEmailRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "emails" ] }, "id": { "type": "string" }, "attributes": { "title": "EmailAttributesSchema", "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sent", "received", "suppressed", "archived", "trashed", "failed", "pending" ], "description": "Lifecycle status. draft = composing, scheduled = workflow owns the send, sent = outbound delivered to SES, received = inbound accepted by broker (replaces the legacy `sent` value used for inbound), suppressed = SES bounce/complaint, archived = user explicitly archived (kept indefinitely, hidden from inbox view), trashed = user moved to Trash bin (default soft DELETE; recoverable, candidate for periodic permanent purge), failed = internal error, pending = transitional." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Whether the email was received from an external sender (inbound, populated by the broker) or composed by the tenant/system and sent out (outbound). Populated at create time; never changes." }, "emailFrom": { "type": "string" }, "emailTo": { "type": "string" }, "emailCc": { "type": "array", "items": { "type": "string" }, "description": "CC recipients. Each entry is an RFC 5322 address string." }, "emailBcc": { "type": "array", "items": { "type": "string" }, "description": "BCC recipients. Each entry is an RFC 5322 address string." }, "subject": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Multilingual subject keyed by IETF BCP 47 locale code (e.g. `en-US`, `pl-PL`). The DAL writes per-locale entries from the AI analyze + translate steps; the UI picks the right key based on `conversationLanguageCode`." }, "body": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Multilingual HTML body keyed by IETF BCP 47 locale code. Same shape as `subject`. Body values are HTML strings; plain-text fallback is derived on send." }, "shortCode": { "type": "string" }, "source": { "type": "string" }, "isReply": { "type": "boolean" }, "isSendable": { "type": "boolean" }, "isExternalSender": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "fileName": { "type": "string", "description": "Display name shown in the mail client and used as the attachment filename on send." }, "url": { "type": "string", "description": "S3 URL of the stored file. For user-uploaded attachments this is the path returned by POST /v1/files; for system-generated attachments (job/persona/report PDFs) it is the resource's own S3 path." }, "type": { "type": "string", "description": "Resource type this attachment belongs to. User-uploaded attachments use `files`; system-generated attachments use the owning resource type: `jobs`, `personas`, `talents`, `candidates`, `reports`, `ads`." }, "fileId": { "type": "string", "description": "When `type == \"files\"`, the file resource ID so the frontend can resolve the latest file metadata (status, processing state) without parsing the URL." }, "size": { "type": "integer", "description": "File size in bytes. Frontend displays it in the compose preview and mail list. Set by the upload flow from the Content-Length of the S3 object; absent on legacy rows." }, "contentType": { "type": "string", "description": "MIME type (e.g. `application/pdf`, `image/png`). Drives icon selection in the UI and the Content-Type header in the outbound MIME part. Absent on legacy rows; frontend should fall back to extension inference." }, "thumbnailUrl": { "type": "string", "description": "Optional S3 URL of a PNG preview (first-page render for PDFs/DOCX). Populated by the file service's conversion pipeline when a preview is available. Absent for non-previewable types." } } }, "description": "Attachments on the email. For user-uploaded attachments: frontend creates a File via POST /v1/files (which returns a presigned PUT URL), uploads to S3, then references the File here with `type: \"files\"` and the returned `url`/`fileId`. For system-generated attachments (job/persona/report PDFs) the eventbus / outbound path populates these automatically." }, "conversationLanguageCode": { "type": "string", "description": "Denormalised copy of the related conversation's languageCode (e.g. `pl-PL`, `en-US`). Avoids an N+1 fetch when the list/detail view needs to pick the right locale for the multilingual subject/body dicts. Source of truth is the conversation row; read-only from the email's perspective." }, "parentEmailId": { "type": "string", "description": "Application-layer pointer to the email this one replies to. Used by the UI to render an 'in reply to' link in thread views. Set by the compose flow (frontend passes the parent on Reply) and by the broker when an inbound email matches an outbound via RFC 5322 In-Reply-To. Separate from meta.reference which carries the raw SMTP header chain." }, "fromUserId": { "type": "string", "description": "Denormalised user id of the sender for outbound emails (the boe workflow user, or the human composer). Frontend joins this against its local user cache to render avatar + display name without a per-row API call. Null on inbound mail." }, "fromCandidateId": { "type": "string", "description": "Denormalised candidate id of the sender for inbound replies from a candidate in an active conversation. Frontend joins this against its local candidate cache to render initials and the candidate name. Null on outbound mail and on anonymous inbound that didn't match a candidate." }, "isSystemSpam": { "type": "boolean", "description": "System-level spam verdict on this email. Set by the broker (or a future classifier) at inbound time; never reflects a single user's opinion. Distinct from `status=suppressed`, which is SES reporting we cannot deliver on OUTBOUND. Frontend's Spam folder unions (my states where isSpam=true) with (emails where isSystemSpam=true)." }, "scheduleId": { "type": "string", "description": "Foreign key to the Schedule resource driving this email's send. Populated by the wait:process workflow action right after it creates the Schedule. Null when no delayed send is pending (drafts, already-sent rows, inbound mail). To cancel the scheduled send, call DELETE /v1/schedules/{scheduleId} - the email eventbus handler listens for SCHEDULE_CANCELLED and reverts the row back to draft automatically." }, "scheduledFireAt": { "type": "string", "description": "Denormalised copy of the owning Schedule's `fireAt` timestamp (ISO 8601). The scheduled-send banner reads this directly so the UI never has to round-trip to /v1/schedules just to render 'Send scheduled for X'. Source of truth is the Schedule; this field stays stable because Schedule.fireAt is immutable post-create." }, "ttl": { "type": "string" }, "sendScheduleDate": { "type": "string", "deprecated": true, "description": "Legacy field from the retired CRUD-scheduler path. Kept as read-only metadata on old rows. New emails do not populate it; scheduling is owned by the workflow engine's wait:process action via the Schedule resource." }, "meta": { "type": "object", "additionalProperties": true }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_email", "description": "Delete Email", "parameters": { "type": "object", "properties": { "permanentDelete": { "type": "string", "description": "Set to true for permanent deletion (row removed from DynamoDB). Defaults to false (soft delete to Trash).", "enum": [ "true", "false" ] } } } } }, { "type": "function", "function": { "name": "email_options", "description": "Email Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_forms", "description": "List Forms", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns forms with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterKind": { "type": "string", "description": "Returns forms of one kind (e.g. candidateSubmission) - the careers/apply editors resolve the application form without paging everything.", "enum": [ "jobBrief", "candidateSubmission", "talentSubmission", "general" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_form", "description": "Create Form", "parameters": { "title": "CreateFormRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateFormRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "forms" ] }, "attributes": { "title": "FormAttributesSchema", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "kind": { "type": "string", "enum": [ "jobBrief", "candidateSubmission", "talentSubmission", "general" ], "default": "general", "description": "Role marker. Identifies which downstream resource this form's\nsubmission becomes:\n - jobBrief: produces a Brief about a Job (email/api intake;\n consumed by the create-job-from-brief workflow).\n - candidateSubmission: produces a Submission about a\n Candidate (apply form intake).\n - talentSubmission: produces a Submission about a Talent.\n - general: catch-all / undecided.\nTenant pins one form per kind as its default via\n`tenant.relationships.forms`. Mirrors the role-marker pattern\nused on Feedback (`stage`)." }, "shortCode": { "type": "string" }, "content": { "type": "string", "description": "The field schema, JSON-encoded: a flat map of `fieldId -> field`.\nA field carries `label` and `description` as locale maps, a\n`type` (text, textarea, select, checkbox, file, email, phone,\ndate, number), `required`, and for a select an `options` list of\n`{value, label}` - the candidate submits `value`, never the\nlocalized label.\n\nA knockout field adds `knockout: true`, `verifies` (the criterion\nit gates on) and `expectedAnswer` (the PASSING answer, matching\none of the option values for a select). The submission gate\nrejects a candidate on a failed knockout without any AI spend, so\na knockout missing `expectedAnswer` is refused: the gate would\nskip it and admit everyone. A knockout on a checkbox is refused\ntoo - a required checkbox renders as must-tick, so \"No\" cannot be\nexpressed and the gate could never fire.\n\nEvery label and option label must carry text in the form's\n`languageCode` or in `en-US` - the locales the apply page falls\nback to. A label that resolves in neither renders blank for the\ncandidate and is refused.\n\nAn apply form (`kind: candidateSubmission`) must keep the\n`fullName`, `email`, `phone` and `cv` fields: the apply page maps\nthem onto first-class submission slots.\n\nRejections come back as one error object per violation, each with\na `source.pointer` at the offending field. Limit: 131072 bytes." }, "publish": { "type": "boolean", "description": "Publish transition. `true` mirrors `content` to the CDN and flips\nthe form to `active`, the state guest submission intake requires.\nSend it on the same PATCH that carries the edit, or on its own to\nrepublish what is already stored. Needs the recruiting tier or\nabove; publishing a form with no content is a 400." }, "languageCode": { "type": "string", "description": "The form's own language as a BCP-47 tag (e.g. `pl-PL`). Stamped by\nthe build pipeline; settable at create and changeable by PATCH.\n\nIt is part of the RENDER FALLBACK CHAIN: the apply page tries the\ncandidate's locale, then this one, then `en-US`. Every label and\noption label must resolve somewhere in that chain - in this locale\nOR in `en-US`, not necessarily both. A form with no `languageCode`\nis held to `en-US` alone. Change it and the labels in the same\nPATCH; the new text is validated against the new chain." }, "revision": { "type": "integer", "description": "Optimistic-concurrency token, bumped atomically on every write.\nSend it back as `If-Match: \"\"` on PATCH to make the\nwrite conditional; a mismatch is a 409 `SM_FORM_STALE`, meaning\nsomeone else saved since your read. Without the header the write\nis unconditional and the last writer wins - which for a form\nmeans silently replacing the whole field schema." }, "translate": { "type": "boolean", "description": "Fill missing locales on the field schema, asynchronously. Fires\nafter the write lands, so it can ride the same PATCH as an edit or\nbe sent alone. Targets the tenant's active languages plus the\nform's own `languageCode`, translating FROM the `en-US` text - a\nfield with no `en-US` label is skipped rather than invented.\n\nFill-only-missing: text already present in a locale is never\noverwritten, and an operator edit that lands mid-run wins (the\nfill re-merges only what is still missing). Field ids,\n`options[].value`, `knockout`, `verifies` and `expectedAnswer` are\nnever touched, so the tokens the submission gate compares survive.\n\nThe outcome lands in `meta.translation`\n(`status`, `translated`, `locales`, `startedAt`, `finishedAt`);\npoll `showForm` for it. Publishing is separate: the filled text\nreaches the apply page on the next `publish: true`." }, "publishedUrl": { "type": "string", "description": "Where the published document lives. Server-managed: the server\nowns the key it wrote, so never compose this URL client-side - a\nURL built from the wrong tenant shortCode is indistinguishable\nfrom a correct one." }, "ttl": { "type": "string" }, "source": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "FormWriteRelationshipsSchema", "type": "object", "description": "WRITE shape for request bodies: the storage-convention plural keys the services and the existing SDK writer classes use. Responses use the wire-shaped RelationshipsSchema instead - the two deliberately differ (PLAN_RELATIONSHIP_CONTRACT.md).", "properties": {} } } } } } } }, { "type": "function", "function": { "name": "forms_options", "description": "Forms Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_form", "description": "Show Form", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_form", "description": "Update Form", "parameters": { "title": "UpdateFormRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateFormRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "forms" ] }, "id": { "type": "string" }, "attributes": { "title": "FormAttributesSchema", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "kind": { "type": "string", "enum": [ "jobBrief", "candidateSubmission", "talentSubmission", "general" ], "default": "general", "description": "Role marker. Identifies which downstream resource this form's\nsubmission becomes:\n - jobBrief: produces a Brief about a Job (email/api intake;\n consumed by the create-job-from-brief workflow).\n - candidateSubmission: produces a Submission about a\n Candidate (apply form intake).\n - talentSubmission: produces a Submission about a Talent.\n - general: catch-all / undecided.\nTenant pins one form per kind as its default via\n`tenant.relationships.forms`. Mirrors the role-marker pattern\nused on Feedback (`stage`)." }, "shortCode": { "type": "string" }, "content": { "type": "string", "description": "The field schema, JSON-encoded: a flat map of `fieldId -> field`.\nA field carries `label` and `description` as locale maps, a\n`type` (text, textarea, select, checkbox, file, email, phone,\ndate, number), `required`, and for a select an `options` list of\n`{value, label}` - the candidate submits `value`, never the\nlocalized label.\n\nA knockout field adds `knockout: true`, `verifies` (the criterion\nit gates on) and `expectedAnswer` (the PASSING answer, matching\none of the option values for a select). The submission gate\nrejects a candidate on a failed knockout without any AI spend, so\na knockout missing `expectedAnswer` is refused: the gate would\nskip it and admit everyone. A knockout on a checkbox is refused\ntoo - a required checkbox renders as must-tick, so \"No\" cannot be\nexpressed and the gate could never fire.\n\nEvery label and option label must carry text in the form's\n`languageCode` or in `en-US` - the locales the apply page falls\nback to. A label that resolves in neither renders blank for the\ncandidate and is refused.\n\nAn apply form (`kind: candidateSubmission`) must keep the\n`fullName`, `email`, `phone` and `cv` fields: the apply page maps\nthem onto first-class submission slots.\n\nRejections come back as one error object per violation, each with\na `source.pointer` at the offending field. Limit: 131072 bytes." }, "publish": { "type": "boolean", "description": "Publish transition. `true` mirrors `content` to the CDN and flips\nthe form to `active`, the state guest submission intake requires.\nSend it on the same PATCH that carries the edit, or on its own to\nrepublish what is already stored. Needs the recruiting tier or\nabove; publishing a form with no content is a 400." }, "languageCode": { "type": "string", "description": "The form's own language as a BCP-47 tag (e.g. `pl-PL`). Stamped by\nthe build pipeline; settable at create and changeable by PATCH.\n\nIt is part of the RENDER FALLBACK CHAIN: the apply page tries the\ncandidate's locale, then this one, then `en-US`. Every label and\noption label must resolve somewhere in that chain - in this locale\nOR in `en-US`, not necessarily both. A form with no `languageCode`\nis held to `en-US` alone. Change it and the labels in the same\nPATCH; the new text is validated against the new chain." }, "revision": { "type": "integer", "description": "Optimistic-concurrency token, bumped atomically on every write.\nSend it back as `If-Match: \"\"` on PATCH to make the\nwrite conditional; a mismatch is a 409 `SM_FORM_STALE`, meaning\nsomeone else saved since your read. Without the header the write\nis unconditional and the last writer wins - which for a form\nmeans silently replacing the whole field schema." }, "translate": { "type": "boolean", "description": "Fill missing locales on the field schema, asynchronously. Fires\nafter the write lands, so it can ride the same PATCH as an edit or\nbe sent alone. Targets the tenant's active languages plus the\nform's own `languageCode`, translating FROM the `en-US` text - a\nfield with no `en-US` label is skipped rather than invented.\n\nFill-only-missing: text already present in a locale is never\noverwritten, and an operator edit that lands mid-run wins (the\nfill re-merges only what is still missing). Field ids,\n`options[].value`, `knockout`, `verifies` and `expectedAnswer` are\nnever touched, so the tokens the submission gate compares survive.\n\nThe outcome lands in `meta.translation`\n(`status`, `translated`, `locales`, `startedAt`, `finishedAt`);\npoll `showForm` for it. Publishing is separate: the filled text\nreaches the apply page on the next `publish: true`." }, "publishedUrl": { "type": "string", "description": "Where the published document lives. Server-managed: the server\nowns the key it wrote, so never compose this URL client-side - a\nURL built from the wrong tenant shortCode is indistinguishable\nfrom a correct one." }, "ttl": { "type": "string" }, "source": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_form", "description": "Delete Form", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "form_options", "description": "Form Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_feedbacks", "description": "List Feedbacks", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns feedbacks with the given status. No default: omit it to list every status (SLA overrides are draft before gate 2 and accepted after it, so a fixed active default would hide them). One filter at a time: combine with filterStage or filterJobId and the request is a 400.", "enum": [ "active", "draft", "accepted", "archived", "failed" ] }, "filterStage": { "type": "string", "description": "Returns feedbacks for the given pipeline stage (StageIndex lookup). One filter at a time.", "enum": [ "screening", "assessment", "interview" ] }, "filterJobId": { "type": "string", "description": "Returns the per-job feedback overrides of the given job (JobIndex lookup on the mirrored jobId; tenant defaults never match). One filter at a time." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_feedback", "description": "Create Feedback", "parameters": { "title": "CreateFeedbackRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateFeedbackRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "feedbacks" ] }, "attributes": { "title": "FeedbackAttributesSchema", "type": "object", "required": [ "name", "stage" ], "properties": { "name": { "type": "string" }, "stage": { "type": "string", "enum": [ "screening", "assessment", "interview" ], "description": "Pipeline stage this feedback configuration applies to. Matches candidate.stage. interview covers both hiring-manager refusals at candidate.stage=interview (declined before the interview, declined after it)." }, "status": { "type": "string", "enum": [ "active", "draft", "accepted", "archived", "failed" ], "description": "active / accepted = sendable (feedback:resolve uses the row; accepted is the gate-2 stamp written by job:accept-artifacts). draft = authored, not sent. archived = soft-deleted, never sent, cannot be pinned as a tenant default. failed = reserved. On create only active or draft are accepted (default active); on update the value must be one of the enum (validated server-side, a bad value is a 400)." }, "source": { "type": "string" }, "jobId": { "type": "string", "description": "Mirror of relationships.jobs[0].id for per-job overrides (server-maintained; absent on tenant defaults). Filter with filterJobId (JobIndex)." }, "outcomes": { "title": "FeedbackOutcomesSchema", "type": "object", "description": "Per-outcome feedback rules. Outcome keys map to candidate.recommendationStatusCode: 1=notFit, 2=maybe, 3=fit. Code 0 (not evaluated) never triggers feedback - the workflow pauses instead.", "properties": { "notFit": { "title": "FeedbackOutcomeRuleSchema", "type": "object", "description": "Feedback rule for a single outcome within a stage. Every field is per-outcome; there are no top-level defaults.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "When false, the workflow skips the feedback email for this outcome. The admin handles the candidate manually." }, "tone": { "type": "string", "enum": [ "casual", "formal", "superFormal" ] }, "transparency": { "type": "string", "enum": [ "generic", "category", "specific" ] }, "delay": { "type": "integer", "default": 72 }, "respectBusinessDays": { "type": "boolean", "default": false }, "aiDisclosure": { "type": "boolean", "default": true }, "signature": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" } } }, "instructions": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "reasons": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } } } }, "feedbackFormUrl": { "type": "string" } } }, "maybe": { "title": "FeedbackOutcomeRuleSchema", "type": "object", "description": "Feedback rule for a single outcome within a stage. Every field is per-outcome; there are no top-level defaults.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "When false, the workflow skips the feedback email for this outcome. The admin handles the candidate manually." }, "tone": { "type": "string", "enum": [ "casual", "formal", "superFormal" ] }, "transparency": { "type": "string", "enum": [ "generic", "category", "specific" ] }, "delay": { "type": "integer", "default": 72 }, "respectBusinessDays": { "type": "boolean", "default": false }, "aiDisclosure": { "type": "boolean", "default": true }, "signature": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" } } }, "instructions": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "reasons": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } } } }, "feedbackFormUrl": { "type": "string" } } }, "fit": { "title": "FeedbackOutcomeRuleSchema", "type": "object", "description": "Feedback rule for a single outcome within a stage. Every field is per-outcome; there are no top-level defaults.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "When false, the workflow skips the feedback email for this outcome. The admin handles the candidate manually." }, "tone": { "type": "string", "enum": [ "casual", "formal", "superFormal" ] }, "transparency": { "type": "string", "enum": [ "generic", "category", "specific" ] }, "delay": { "type": "integer", "default": 72 }, "respectBusinessDays": { "type": "boolean", "default": false }, "aiDisclosure": { "type": "boolean", "default": true }, "signature": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" } } }, "instructions": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "reasons": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } } } }, "feedbackFormUrl": { "type": "string" } } } } }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "FeedbackWriteRelationshipsSchema", "type": "object", "description": "WRITE shape for request bodies: the storage-convention plural keys the services and the existing SDK writer classes use. Responses use the wire-shaped RelationshipsSchema instead - the two deliberately differ (PLAN_RELATIONSHIP_CONTRACT.md).", "properties": { "jobs": { "title": "FeedbackRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "feedbacks_options", "description": "Feedbacks Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_feedback", "description": "Show Feedback", "parameters": { "type": "object", "properties": { "feedbackId": { "type": "string", "description": "feedbackId parameter" } }, "required": [ "feedbackId" ] } } }, { "type": "function", "function": { "name": "update_feedback", "description": "Update Feedback", "parameters": { "type": "object", "properties": { "feedbackId": { "type": "string", "description": "feedbackId parameter" }, "requestBody": { "title": "UpdateFeedbackRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateFeedbackRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "feedbacks" ] }, "id": { "type": "string" }, "attributes": { "title": "UpdateFeedbackRequestBodyDataAttributes", "type": "object", "description": "Partial update: only the fields present are merged (no field is required, unlike FeedbackAttributesSchema on create). Omitting a field leaves it unchanged.", "properties": { "name": { "type": "string" }, "stage": { "type": "string", "enum": [ "screening", "assessment", "interview" ] }, "status": { "type": "string", "enum": [ "active", "draft", "accepted", "archived", "failed" ] }, "source": { "type": "string" }, "outcomes": { "title": "FeedbackOutcomesSchema", "type": "object", "description": "Per-outcome feedback rules. Outcome keys map to candidate.recommendationStatusCode: 1=notFit, 2=maybe, 3=fit. Code 0 (not evaluated) never triggers feedback - the workflow pauses instead.", "properties": { "notFit": { "title": "FeedbackOutcomeRuleSchema", "type": "object", "description": "Feedback rule for a single outcome within a stage. Every field is per-outcome; there are no top-level defaults.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "When false, the workflow skips the feedback email for this outcome. The admin handles the candidate manually." }, "tone": { "type": "string", "enum": [ "casual", "formal", "superFormal" ] }, "transparency": { "type": "string", "enum": [ "generic", "category", "specific" ] }, "delay": { "type": "integer", "default": 72 }, "respectBusinessDays": { "type": "boolean", "default": false }, "aiDisclosure": { "type": "boolean", "default": true }, "signature": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" } } }, "instructions": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "reasons": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } } } }, "feedbackFormUrl": { "type": "string" } } }, "maybe": { "title": "FeedbackOutcomeRuleSchema", "type": "object", "description": "Feedback rule for a single outcome within a stage. Every field is per-outcome; there are no top-level defaults.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "When false, the workflow skips the feedback email for this outcome. The admin handles the candidate manually." }, "tone": { "type": "string", "enum": [ "casual", "formal", "superFormal" ] }, "transparency": { "type": "string", "enum": [ "generic", "category", "specific" ] }, "delay": { "type": "integer", "default": 72 }, "respectBusinessDays": { "type": "boolean", "default": false }, "aiDisclosure": { "type": "boolean", "default": true }, "signature": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" } } }, "instructions": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "reasons": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } } } }, "feedbackFormUrl": { "type": "string" } } }, "fit": { "title": "FeedbackOutcomeRuleSchema", "type": "object", "description": "Feedback rule for a single outcome within a stage. Every field is per-outcome; there are no top-level defaults.", "properties": { "enabled": { "type": "boolean", "default": false, "description": "When false, the workflow skips the feedback email for this outcome. The admin handles the candidate manually." }, "tone": { "type": "string", "enum": [ "casual", "formal", "superFormal" ] }, "transparency": { "type": "string", "enum": [ "generic", "category", "specific" ] }, "delay": { "type": "integer", "default": 72 }, "respectBusinessDays": { "type": "boolean", "default": false }, "aiDisclosure": { "type": "boolean", "default": true }, "signature": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" } } }, "instructions": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "reasons": { "type": "array", "items": { "type": "string" } }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "url": { "type": "string" } } } }, "feedbackFormUrl": { "type": "string" } } } } } } }, "relationships": { "title": "FeedbackWriteRelationshipsSchema", "type": "object", "description": "WRITE shape for request bodies: the storage-convention plural keys the services and the existing SDK writer classes use. Responses use the wire-shaped RelationshipsSchema instead - the two deliberately differ (PLAN_RELATIONSHIP_CONTRACT.md).", "properties": { "jobs": { "title": "FeedbackRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } }, "required": [ "feedbackId", "requestBody" ] } } }, { "type": "function", "function": { "name": "delete_feedback", "description": "Delete Feedback", "parameters": { "type": "object", "properties": { "feedbackId": { "type": "string", "description": "feedbackId parameter" }, "permanentDelete": { "type": "string", "description": "Set to true for permanent deletion.", "enum": [ "true", "false" ] } }, "required": [ "feedbackId" ] } } }, { "type": "function", "function": { "name": "feedback_options", "description": "Feedback Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_surveys", "description": "List Surveys", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns surveys with the current status.", "enum": [ "draft", "active", "archived" ] }, "filterKind": { "type": "string", "description": "Returns surveys of one kind.", "enum": [ "cnps", "general" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_survey", "description": "Create Survey", "parameters": { "title": "CreateSurveyRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateSurveyRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "surveys" ] }, "attributes": { "title": "CreateSurveyRequestBodyDataAttributes", "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 5, "maxLength": 255 }, "kind": { "type": "string", "enum": [ "cnps", "general" ] }, "content": { "title": "SurveyContentSchema", "type": "object", "description": "The questionnaire: a locale-keyed title plus an ordered question list.", "properties": { "title": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Locale map, e.g. {\"en-US\": \"Your application experience\", \"pl-PL\": \"...\"}. en-US is required to publish; clients render by locale prefix with en-US fallback." }, "questions": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "title": "SurveyQuestionSchema", "type": "object", "description": "One question. Common fields: questionId (server-assigned when\nomitted; stable forever after - answers key on it), type, text\n(locale map), required. Per-type fields:\n scale - scaleMin/scaleMax (integers, min < max),\n optional scaleLabels {min, max} locale maps,\n optional subtype \"nps\" (pins 0-10, enables\n detractor/passive/promoter classification)\n single-choice / multiple-choice\n - options: 2-20 entries of {value, label};\n value is a stable lowercase slug (a-z, 0-9, -)\n the recipient submits; label is a locale map\n open-text - maxLength (default 2000, max 5000)", "properties": { "questionId": { "type": "string", "maxLength": 64, "description": "Stable identity of the question. Server-assigned uuid hex when omitted at save." }, "type": { "type": "string", "enum": [ "scale", "single-choice", "multiple-choice", "open-text" ] }, "subtype": { "type": "string", "enum": [ "nps" ], "description": "scale only. nps pins scaleMin=0/scaleMax=10 and classifies answers detractor/passive/promoter on submit." }, "required": { "type": "boolean", "default": false }, "text": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Locale map of the question text. en-US required to publish." }, "scaleMin": { "type": "integer", "minimum": 0, "maximum": 100 }, "scaleMax": { "type": "integer", "minimum": 0, "maximum": 100 }, "scaleLabels": { "type": "object", "description": "Optional locale maps for the scale endpoints.", "properties": { "min": { "type": "object", "additionalProperties": { "type": "string" } }, "max": { "type": "object", "additionalProperties": { "type": "string" } } } }, "options": { "type": "array", "minItems": 2, "maxItems": 20, "items": { "title": "SurveyQuestionOptionSchema", "type": "object", "properties": { "value": { "type": "string", "maxLength": 64, "description": "Stable lowercase slug (a-z, 0-9, -). What the recipient submits - locale-proof, never the label." }, "label": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Locale map. en-US required to publish." } } } }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 5000, "description": "open-text only. Default 2000." } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "surveys_options", "description": "Surveys Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_survey", "description": "Show Survey", "parameters": { "type": "object", "properties": { "surveyId": { "type": "string", "description": "surveyId parameter" } }, "required": [ "surveyId" ] } } }, { "type": "function", "function": { "name": "update_survey", "description": "Update Survey", "parameters": { "type": "object", "properties": { "surveyId": { "type": "string", "description": "surveyId parameter" }, "requestBody": { "title": "UpdateSurveyRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateSurveyRequestBodyData", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "surveys" ] }, "id": { "type": "string" }, "attributes": { "title": "UpdateSurveyRequestBodyDataAttributes", "type": "object", "properties": { "name": { "type": "string", "minLength": 5, "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "description": "active = publish. Allowed transitions: draft->active, draft->archived, active->archived, archived->active; active->active re-publishes the edited draft." }, "content": { "title": "SurveyContentSchema", "type": "object", "description": "The questionnaire: a locale-keyed title plus an ordered question list.", "properties": { "title": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Locale map, e.g. {\"en-US\": \"Your application experience\", \"pl-PL\": \"...\"}. en-US is required to publish; clients render by locale prefix with en-US fallback." }, "questions": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "title": "SurveyQuestionSchema", "type": "object", "description": "One question. Common fields: questionId (server-assigned when\nomitted; stable forever after - answers key on it), type, text\n(locale map), required. Per-type fields:\n scale - scaleMin/scaleMax (integers, min < max),\n optional scaleLabels {min, max} locale maps,\n optional subtype \"nps\" (pins 0-10, enables\n detractor/passive/promoter classification)\n single-choice / multiple-choice\n - options: 2-20 entries of {value, label};\n value is a stable lowercase slug (a-z, 0-9, -)\n the recipient submits; label is a locale map\n open-text - maxLength (default 2000, max 5000)", "properties": { "questionId": { "type": "string", "maxLength": 64, "description": "Stable identity of the question. Server-assigned uuid hex when omitted at save." }, "type": { "type": "string", "enum": [ "scale", "single-choice", "multiple-choice", "open-text" ] }, "subtype": { "type": "string", "enum": [ "nps" ], "description": "scale only. nps pins scaleMin=0/scaleMax=10 and classifies answers detractor/passive/promoter on submit." }, "required": { "type": "boolean", "default": false }, "text": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Locale map of the question text. en-US required to publish." }, "scaleMin": { "type": "integer", "minimum": 0, "maximum": 100 }, "scaleMax": { "type": "integer", "minimum": 0, "maximum": 100 }, "scaleLabels": { "type": "object", "description": "Optional locale maps for the scale endpoints.", "properties": { "min": { "type": "object", "additionalProperties": { "type": "string" } }, "max": { "type": "object", "additionalProperties": { "type": "string" } } } }, "options": { "type": "array", "minItems": 2, "maxItems": 20, "items": { "title": "SurveyQuestionOptionSchema", "type": "object", "properties": { "value": { "type": "string", "maxLength": 64, "description": "Stable lowercase slug (a-z, 0-9, -). What the recipient submits - locale-proof, never the label." }, "label": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Locale map. en-US required to publish." } } } }, "maxLength": { "type": "integer", "minimum": 1, "maximum": 5000, "description": "open-text only. Default 2000." } } } } } } } } } } } } }, "required": [ "surveyId", "requestBody" ] } } }, { "type": "function", "function": { "name": "delete_survey", "description": "Delete Survey", "parameters": { "type": "object", "properties": { "surveyId": { "type": "string", "description": "surveyId parameter" }, "permanentDelete": { "type": "string", "description": "true removes the row instead of archiving it.", "enum": [ "true", "false" ] } }, "required": [ "surveyId" ] } } }, { "type": "function", "function": { "name": "survey_options", "description": "Survey Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_responses", "description": "List Responses", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns responses with the current status.", "enum": [ "pending", "completed", "expired" ] }, "filterSurveyId": { "type": "string", "description": "Filter by the survey definition the response belongs to." }, "filterCandidateId": { "type": "string", "description": "Filter by the candidate the invitation was sent to." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "responses_options", "description": "Responses Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_response", "description": "Show Response", "parameters": { "type": "object", "properties": { "responseId": { "type": "string", "description": "responseId parameter" } }, "required": [ "responseId" ] } } }, { "type": "function", "function": { "name": "response_options", "description": "Response Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_guest_response", "description": "Show Guest Response", "parameters": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "Base tenant id from the emailed link. Half of the guest auth pair." }, "token": { "type": "string", "description": "Per-response accessToken from the emailed link. Compared with hmac.compare_digest; mismatch returns 404." } }, "required": [ "tenantId", "token" ] } } }, { "type": "function", "function": { "name": "submit_guest_response", "description": "Submit Guest Response", "parameters": { "title": "SubmitGuestResponseRequestBody", "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "title": "SubmitGuestResponseRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "responses" ] }, "id": { "type": "string" }, "attributes": { "title": "SubmitGuestResponseRequestBodyDataAttributes", "type": "object", "required": [ "answers" ], "properties": { "answers": { "type": "object", "description": "Keyed by questionId. Scale values are classified server-side (0-6 detractor, 7-8 passive, 9-10 promoter for nps questions)." } } } } }, "meta": { "title": "GuestResponseMetaSchema", "description": "Auth context for the unauthenticated PATCH\n/v1/guest/responses/{id}. Both values come from the emailed link,\nnever from a session - there is no authorizer on the guest path.\ntenantId is the BASE tenant id; accessToken is the per-response\ntoken minted at create and compared with hmac.compare_digest. Any\nmismatch returns 404, intentionally indistinguishable from\n\"response not found\" so existence is never leaked.", "type": "object", "required": [ "tenantId", "accessToken" ], "properties": { "tenantId": { "type": "string" }, "accessToken": { "type": "string" } } } } } } }, { "type": "function", "function": { "name": "guest_response_options", "description": "Guest Response Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_documents", "description": "List Documents", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns documents with the current status.", "enum": [ "draft", "pending", "completed", "declined", "expired", "withdrawn" ] }, "filterCandidateId": { "type": "string", "description": "Filter by the candidate the document belongs to." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_document", "description": "Create Document", "parameters": { "title": "CreateDocumentRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateDocumentRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "documents" ] }, "attributes": { "title": "CreateDocumentRequestBodyDataAttributes", "type": "object", "required": [ "documentType" ], "properties": { "documentType": { "type": "string", "enum": [ "employment_offer", "employment_contract", "b2b_contract", "nda", "policy", "consent" ] }, "process": { "type": "string", "enum": [ "offer", "contract", "document" ] }, "title": { "type": "object", "additionalProperties": { "type": "string" } }, "languageCode": { "type": "string" }, "organizationName": { "type": "string" }, "body": { "type": "array", "items": { "type": "object" } }, "fields": { "type": "array", "items": { "type": "object" } }, "participants": { "type": "array", "items": { "type": "object" } }, "expiresAt": { "type": "string", "format": "date-time" } } }, "relationships": { "title": "DocumentRelationshipsSchema", "type": "object", "properties": { "candidate": { "title": "DocumentRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "job": { "title": "DocumentRelationshipsJobSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "conversation": { "title": "DocumentRelationshipsConversationSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "documents_options", "description": "Documents Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_document", "description": "Show Document", "parameters": { "type": "object", "properties": { "documentId": { "type": "string", "description": "documentId parameter" } }, "required": [ "documentId" ] } } }, { "type": "function", "function": { "name": "update_document", "description": "Update Document", "parameters": { "type": "object", "properties": { "documentId": { "type": "string", "description": "documentId parameter" }, "requestBody": { "title": "UpdateDocumentRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateDocumentRequestBodyData", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "documents" ] }, "id": { "type": "string" }, "attributes": { "title": "UpdateDocumentRequestBodyDataAttributes", "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "withdrawn" ], "description": "pending = the SEND door (draft only); withdrawn = withdraw a sent document." }, "title": { "type": "object", "additionalProperties": { "type": "string" } }, "languageCode": { "type": "string" }, "organizationName": { "type": "string" }, "body": { "type": "array", "items": { "type": "object" } }, "fields": { "type": "array", "items": { "type": "object" } }, "participants": { "type": "array", "items": { "type": "object" } }, "expiresAt": { "type": "string", "format": "date-time" } } }, "relationships": { "title": "DocumentRelationshipsSchema", "type": "object", "properties": { "candidate": { "title": "DocumentRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "job": { "title": "DocumentRelationshipsJobSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "conversation": { "title": "DocumentRelationshipsConversationSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } }, "required": [ "documentId", "requestBody" ] } } }, { "type": "function", "function": { "name": "delete_document", "description": "Delete Document", "parameters": { "type": "object", "properties": { "documentId": { "type": "string", "description": "documentId parameter" } }, "required": [ "documentId" ] } } }, { "type": "function", "function": { "name": "document_options", "description": "Document Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_guest_document", "description": "Show Guest Document", "parameters": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "Base tenant id from the emailed link. Part of the guest auth." }, "token": { "type": "string", "description": "Per-participant accessToken from the emailed link. Compared with hmac.compare_digest; mismatch returns 404." }, "process": { "type": "string", "description": "The link's {process} path segment (offer | contract | document). Mismatch with the row returns 404.", "enum": [ "offer", "contract", "document" ] } }, "required": [ "tenantId", "token" ] } } }, { "type": "function", "function": { "name": "submit_guest_document", "description": "Submit Guest Document", "parameters": { "title": "SubmitGuestDocumentRequestBody", "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "title": "SubmitGuestDocumentRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "documents" ] }, "id": { "type": "string" }, "attributes": { "title": "SubmitGuestDocumentRequestBodyDataAttributes", "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "VIEW", "ACCEPT", "DECLINE" ] }, "confirmations": { "type": "array", "items": { "type": "string" } } } } } }, "meta": { "title": "GuestDocumentMetaSchema", "description": "Auth context for the unauthenticated PATCH\n/v1/guest/documents/{id}. Both values come from the emailed link,\nnever from a session. tenantId is the BASE tenant id; accessToken\nis the per-participant token minted at send and compared with\nhmac.compare_digest. Any mismatch returns 404, intentionally\nindistinguishable from \"document not found\".", "type": "object", "required": [ "tenantId", "accessToken" ], "properties": { "tenantId": { "type": "string" }, "accessToken": { "type": "string" } } } } } } }, { "type": "function", "function": { "name": "guest_document_options", "description": "Guest Document Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_careers", "description": "List Careers", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "filterStatus parameter", "enum": [ "draft", "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_career", "description": "Create Career", "parameters": { "title": "CreateCareerRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateCareerRequestBodyData", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "careers" ] }, "attributes": { "title": "CreateCareerRequestBodyDataAttributes", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceLanguage": { "type": "string", "description": "BCP-47 tag; defaults to en-US. Seeds the skeleton's locale." }, "content": { "title": "CareersContentSchema", "type": "object", "description": "Ordered-blocks careers document. Locale keys are BCP-47 (en-US,\npl-PL, ...). Publish rules (mirrored by the editor): schemaVersion\n1; 1-24 blocks with unique ids; exactly one enabled hero (FIRST\namong enabled blocks) and one enabled positions; <=12 items per\nrepeater; every locale-map string of an ENABLED block non-empty for\nevery locale in `locales`; `locales` is a non-empty subset of the\ntenant's activeLanguages plus sourceLanguage and must contain\nsourceLanguage; absolute URLs only under the tenant's OWN CDN\nprefixes (tenants/{shortCode}/ or tenants/{tenantId}/) OR an https\nvideo embed on youtube.com / www.youtube.com / youtu.be /\nyoutube-nocookie.com / vimeo.com / player.vimeo.com - the embed\nallowlist applies ANYWHERE in the tree, is matched on the parsed\nHOST (not a string prefix) and never accepts http; no < or > in\ntext; <=131072 BYTES (UTF-8).", "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "sourceLanguage": { "type": "string", "description": "BCP-47 tag." }, "locales": { "type": "array", "items": { "type": "string" }, "description": "The locales the page publishes in. The public language switcher offers exactly these." }, "theme": { "title": "CareersThemeSchema", "type": "object", "description": "Optional per-tenant palette, published alongside `branding` in\nthe public document. Absent means the page renders the product\ndefaults. Values are interpolated into CSS custom properties on\na PUBLIC page, so each is pattern-bounded rather than free-form\nCSS. Unknown keys are ignored (forward-compatible), but\n`primaryColor` is required once the object is present.", "properties": { "primaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "6-digit hex, e.g. #1a73e8." }, "secondaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "buttonRadius": { "type": "integer", "minimum": 0, "maximum": 32, "description": "Corner radius in PIXELS. A bounded number, not a CSS length string." } } }, "blocks": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "title": "CareersBlockSchema", "type": "object", "description": "One page section. `data` is the block-type-specific payload: plain\nfields (icon names, urls) plus locale maps\n({\"en-US\": \"...\", \"pl-PL\": \"...\"}) for every visitor-facing string;\nrepeaters are arrays of such objects (<=12 items). The catalog is\nCLOSED - there is no free-form HTML block (XSS door on a public\npage).", "properties": { "id": { "type": "string", "maxLength": 64, "description": "Stable within the document; [A-Za-z0-9_-]." }, "type": { "type": "string", "enum": [ "hero", "stats", "positions", "features", "team", "testimonials", "faq", "gallery", "cta", "richText" ] }, "enabled": { "type": "boolean", "description": "Disabled blocks stay in the draft (and keep translations) but never ship to the public doc and are locale-exempt at publish." }, "data": { "type": "object", "additionalProperties": true } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "careers_options", "description": "Careers Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_career", "description": "Show Career", "parameters": { "type": "object", "properties": { "careerId": { "type": "string", "description": "careerId parameter" } }, "required": [ "careerId" ] } } }, { "type": "function", "function": { "name": "update_career", "description": "Update Career", "parameters": { "type": "object", "properties": { "careerId": { "type": "string", "description": "careerId parameter" }, "requestBody": { "title": "UpdateCareerRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateCareerRequestBodyData", "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "careers" ] }, "id": { "type": "string" }, "attributes": { "title": "UpdateCareerRequestBodyDataAttributes", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "status": { "type": "string", "enum": [ "draft", "active", "archived" ], "description": "active = publish (writes the CDN doc). archived = takedown (removes it; repeat to retry). Allowed transitions: draft->active, draft->archived, active->archived, archived->active." }, "sourceLanguage": { "type": "string", "description": "BCP-47 tag." }, "translate": { "type": "boolean", "description": "Write-only: async-fill missing locale entries of the draft from sourceLanguage. Sent with `generate`, it runs AFTER the generator instead of racing it." }, "generate": { "type": "boolean", "description": "Write-only: async-compose a WHOLE draft from the tenant's brand and its published live roles. Cannot ride a status change; refused on an archived page; a draft that already carries authored text is a 409 SM_CAREERS_DRAFT_NOT_EMPTY without generateOverwrite. Progress in meta.generation." }, "generateOverwrite": { "type": "boolean", "description": "Write-only: consent to replace a draft that already has text. Meaningless without `generate`." }, "content": { "title": "CareersContentSchema", "type": "object", "description": "Ordered-blocks careers document. Locale keys are BCP-47 (en-US,\npl-PL, ...). Publish rules (mirrored by the editor): schemaVersion\n1; 1-24 blocks with unique ids; exactly one enabled hero (FIRST\namong enabled blocks) and one enabled positions; <=12 items per\nrepeater; every locale-map string of an ENABLED block non-empty for\nevery locale in `locales`; `locales` is a non-empty subset of the\ntenant's activeLanguages plus sourceLanguage and must contain\nsourceLanguage; absolute URLs only under the tenant's OWN CDN\nprefixes (tenants/{shortCode}/ or tenants/{tenantId}/) OR an https\nvideo embed on youtube.com / www.youtube.com / youtu.be /\nyoutube-nocookie.com / vimeo.com / player.vimeo.com - the embed\nallowlist applies ANYWHERE in the tree, is matched on the parsed\nHOST (not a string prefix) and never accepts http; no < or > in\ntext; <=131072 BYTES (UTF-8).", "properties": { "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "sourceLanguage": { "type": "string", "description": "BCP-47 tag." }, "locales": { "type": "array", "items": { "type": "string" }, "description": "The locales the page publishes in. The public language switcher offers exactly these." }, "theme": { "title": "CareersThemeSchema", "type": "object", "description": "Optional per-tenant palette, published alongside `branding` in\nthe public document. Absent means the page renders the product\ndefaults. Values are interpolated into CSS custom properties on\na PUBLIC page, so each is pattern-bounded rather than free-form\nCSS. Unknown keys are ignored (forward-compatible), but\n`primaryColor` is required once the object is present.", "properties": { "primaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "6-digit hex, e.g. #1a73e8." }, "secondaryColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "buttonRadius": { "type": "integer", "minimum": 0, "maximum": 32, "description": "Corner radius in PIXELS. A bounded number, not a CSS length string." } } }, "blocks": { "type": "array", "minItems": 1, "maxItems": 24, "items": { "title": "CareersBlockSchema", "type": "object", "description": "One page section. `data` is the block-type-specific payload: plain\nfields (icon names, urls) plus locale maps\n({\"en-US\": \"...\", \"pl-PL\": \"...\"}) for every visitor-facing string;\nrepeaters are arrays of such objects (<=12 items). The catalog is\nCLOSED - there is no free-form HTML block (XSS door on a public\npage).", "properties": { "id": { "type": "string", "maxLength": 64, "description": "Stable within the document; [A-Za-z0-9_-]." }, "type": { "type": "string", "enum": [ "hero", "stats", "positions", "features", "team", "testimonials", "faq", "gallery", "cta", "richText" ] }, "enabled": { "type": "boolean", "description": "Disabled blocks stay in the draft (and keep translations) but never ship to the public doc and are locale-exempt at publish." }, "data": { "type": "object", "additionalProperties": true } } } } } } } } } } } } }, "required": [ "careerId", "requestBody" ] } } }, { "type": "function", "function": { "name": "delete_career", "description": "Delete Career", "parameters": { "type": "object", "properties": { "careerId": { "type": "string", "description": "careerId parameter" } }, "required": [ "careerId" ] } } }, { "type": "function", "function": { "name": "career_options", "description": "Career Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_schedules", "description": "List Schedules", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Filter by status. Omit to return all.", "enum": [ "pending", "fired", "cancelled", "failed" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_schedule", "description": "Create Schedule", "parameters": { "title": "CreateScheduleRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateScheduleRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "schedules" ] }, "attributes": { "title": "ScheduleAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Optional human-readable label for the schedule." }, "status": { "type": "string", "enum": [ "pending", "fired", "cancelled", "failed", "paused" ], "description": "Lifecycle. `pending` is armed and will fire. `fired`/`failed` are terminal. `cancelled` is terminal (hard cancel via DELETE). `paused` is pause-for-edit: EventBridge entry is removed but the row stays re-activatable by PATCH back to `pending` with a new `fireAt`." }, "fireAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the schedule fires. Absolute; compute delayMinutes client-side if needed." }, "firedAt": { "type": "string", "format": "date-time", "description": "Set by the dispatcher when the schedule actually fires." }, "target": { "title": "ScheduleTargetSchema", "type": "object", "description": "What to invoke when the schedule fires.", "required": [ "type", "actionName" ], "properties": { "type": { "type": "string", "enum": [ "action" ], "description": "Target kind. Only `action` is supported today; the dispatcher invokes the matching action Lambda." }, "actionName": { "type": "string", "description": "Action identifier (e.g. `email:send`, `call:initiate`). Resolved by the same convention the workflow engine uses - `resource:verb` maps to `sm-${env}-tb-service-action-function-${resource}-${verb}`." }, "input": { "type": "object", "description": "Payload passed to the action Lambda. Shape is action-specific." } } }, "result": { "type": "object", "description": "Dispatcher's recorded result after firing (status, messageId, or error detail). Server-managed." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "ScheduleRelationshipsSchema", "type": "object", "description": "Optional audit links. None required; use the ones relevant to the scheduled action.", "properties": { "candidate": { "title": "ScheduleRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "job": { "title": "ScheduleRelationshipsJobSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "conversation": { "title": "ScheduleRelationshipsConversationSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "talent": { "title": "ScheduleRelationshipsTalentSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "user": { "title": "ScheduleRelationshipsUserSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "email": { "title": "ScheduleRelationshipsEmailSchema", "type": "object", "description": "The email this schedule was armed for. Set by wait:process so the email service can denormalise scheduleId back onto the email row when SCHEDULE_CREATED fires.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "schedules_options", "description": "Schedules Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_schedule", "description": "Show Schedule", "parameters": { "type": "object", "properties": { "scheduleId": { "type": "string", "description": "scheduleId parameter" } }, "required": [ "scheduleId" ] } } }, { "type": "function", "function": { "name": "update_schedule", "description": "Update Schedule", "parameters": { "type": "object", "properties": { "scheduleId": { "type": "string", "description": "scheduleId parameter" }, "requestBody": { "title": "UpdateScheduleRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateScheduleRequestBodyData", "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "schedules" ] }, "id": { "type": "string" }, "attributes": { "title": "ScheduleAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Optional human-readable label for the schedule." }, "status": { "type": "string", "enum": [ "pending", "fired", "cancelled", "failed", "paused" ], "description": "Lifecycle. `pending` is armed and will fire. `fired`/`failed` are terminal. `cancelled` is terminal (hard cancel via DELETE). `paused` is pause-for-edit: EventBridge entry is removed but the row stays re-activatable by PATCH back to `pending` with a new `fireAt`." }, "fireAt": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp when the schedule fires. Absolute; compute delayMinutes client-side if needed." }, "firedAt": { "type": "string", "format": "date-time", "description": "Set by the dispatcher when the schedule actually fires." }, "target": { "title": "ScheduleTargetSchema", "type": "object", "description": "What to invoke when the schedule fires.", "required": [ "type", "actionName" ], "properties": { "type": { "type": "string", "enum": [ "action" ], "description": "Target kind. Only `action` is supported today; the dispatcher invokes the matching action Lambda." }, "actionName": { "type": "string", "description": "Action identifier (e.g. `email:send`, `call:initiate`). Resolved by the same convention the workflow engine uses - `resource:verb` maps to `sm-${env}-tb-service-action-function-${resource}-${verb}`." }, "input": { "type": "object", "description": "Payload passed to the action Lambda. Shape is action-specific." } } }, "result": { "type": "object", "description": "Dispatcher's recorded result after firing (status, messageId, or error detail). Server-managed." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "ScheduleRelationshipsSchema", "type": "object", "description": "Optional audit links. None required; use the ones relevant to the scheduled action.", "properties": { "candidate": { "title": "ScheduleRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "job": { "title": "ScheduleRelationshipsJobSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "conversation": { "title": "ScheduleRelationshipsConversationSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "talent": { "title": "ScheduleRelationshipsTalentSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "user": { "title": "ScheduleRelationshipsUserSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "email": { "title": "ScheduleRelationshipsEmailSchema", "type": "object", "description": "The email this schedule was armed for. Set by wait:process so the email service can denormalise scheduleId back onto the email row when SCHEDULE_CREATED fires.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } }, "required": [ "scheduleId", "requestBody" ] } } }, { "type": "function", "function": { "name": "delete_schedule", "description": "Cancel Schedule", "parameters": { "type": "object", "properties": { "scheduleId": { "type": "string", "description": "scheduleId parameter" }, "permanentDelete": { "type": "string", "description": "Set to true for permanent deletion.", "enum": [ "true", "false" ] } }, "required": [ "scheduleId" ] } } }, { "type": "function", "function": { "name": "schedule_options", "description": "Schedule Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "create_submission", "description": "Create Submission", "parameters": { "title": "CreateSubmissionRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateSubmissionRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "submissions" ] }, "attributes": { "title": "SubmissionAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Required on create" }, "email": { "type": "string", "description": "Required on create" }, "phone": { "type": "string" }, "channel": { "type": "string", "enum": [ "form", "email", "call", "chat", "api", "agent" ], "description": "How the submission entered the system" }, "source": { "type": "string", "description": "Where the candidate originated (e.g., careerPage, jobBoard, linkedin, talentPool)" }, "type": { "type": "string", "enum": [ "candidate", "talent" ], "description": "Submission type - determines which workflow to trigger" }, "status": { "type": "string", "enum": [ "received", "processing", "processed", "failed", "waiting" ] }, "language": { "type": "string" }, "qualityScore": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Aggregate quality score (1-5 stars) based on answer relevance, clarity, and completeness. AI-generated, recruiter-overridable." }, "fields": { "type": "object", "description": "Form fields keyed by field identifier. Each field contains localized content grouped by language code. Structure: {fieldKey: {langCode: {label, description, value, type, relevance, clarity, completeness, confidence, reasoning}}}." }, "files": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "bucket": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "fileKey": { "type": "string", "description": "S3 key in the submission bucket. The screening workflow reads files.N.fileKey." }, "originalFilename": { "type": "string", "description": "Original filename as uploaded/imported. The screening workflow reads files.N.originalFilename." } } } }, "referral": { "type": "object", "properties": { "referrerName": { "type": "string" }, "referrerEmail": { "type": "string" }, "relationship": { "type": "string" }, "note": { "type": "string" } } }, "consent": { "type": "object", "properties": { "current": { "type": "boolean" }, "future": { "type": "boolean" } } }, "meta": { "type": "object", "description": "Free-form metadata. meta.external carries ATS import correlation ({source, jobShortCode, talentShortCode, applicationShortCode, ttl}); meta.userId is stamped server-side on create. CREATE-ONLY today: the update path ignores meta." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "SubmissionWriteRelationshipsSchema", "type": "object", "description": "WRITE shape for request bodies: the storage-convention plural keys the services and the existing SDK writer classes use. Responses use the wire-shaped RelationshipsSchema instead - the two deliberately differ (PLAN_RELATIONSHIP_CONTRACT.md).", "properties": { "forms": { "title": "SubmissionRelationshipsFormsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "jobs": { "title": "SubmissionRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "talents": { "title": "SubmissionRelationshipsTalentsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "candidates": { "title": "SubmissionRelationshipsCandidatesSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "list_submissions", "description": "List Submissions", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns submissions with the current status. `waiting` = parked until the target job activates (released by submission:release).", "enum": [ "received", "processing", "processed", "failed", "waiting" ] }, "filterEmail": { "type": "string", "description": "Filter submissions by email address." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "submissions_options", "description": "Submissions Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "create_guest_submission", "description": "Create Submission (Guest)", "parameters": { "type": "object", "required": [ "name", "email", "tenantId", "formId" ], "properties": { "tenantId": { "type": "string" }, "formId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "files": { "type": "array", "items": { "type": "object", "properties": { "fileKey": { "type": "string" }, "originalFilename": { "type": "string" } } } }, "fields": { "type": "object", "description": "Form fields keyed by identifier. Each field: {label: string, description: string, value: string, type: 'text'|'number'|'date'|'select'|'checkbox'}." }, "language": { "type": "string" }, "jobId": { "type": "string" }, "referral": { "type": "object", "properties": { "referrerName": { "type": "string" }, "referrerEmail": { "type": "string" }, "relationship": { "type": "string" }, "note": { "type": "string" } } }, "source": { "type": "string", "description": "Where the candidate found the job (e.g., careerPage, jobBoard, linkedin)" }, "consentCurrent": { "type": "boolean" }, "consentFuture": { "type": "boolean" } } } } }, { "type": "function", "function": { "name": "guest_submissions_options", "description": "Guest Submissions Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "upload_guest_submission_file", "description": "Upload Submission File (Guest)", "parameters": { "type": "object", "required": [ "fileName", "contentType", "tenantId", "formId" ], "properties": { "fileName": { "type": "string" }, "contentType": { "type": "string" }, "tenantId": { "type": "string" }, "formId": { "type": "string" } } } } }, { "type": "function", "function": { "name": "guest_submission_uploads_options", "description": "Guest Submission Uploads Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_submission", "description": "Show Submission", "parameters": { "type": "object", "properties": { "submissionId": { "type": "string", "description": "submissionId parameter" } }, "required": [ "submissionId" ] } } }, { "type": "function", "function": { "name": "update_submission", "description": "Update Submission", "parameters": { "type": "object", "properties": { "submissionId": { "type": "string", "description": "submissionId parameter" }, "requestBody": { "title": "UpdateSubmissionRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateSubmissionRequestBodyData", "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "submissions" ] }, "id": { "type": "string" }, "attributes": { "title": "SubmissionAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Required on create" }, "email": { "type": "string", "description": "Required on create" }, "phone": { "type": "string" }, "channel": { "type": "string", "enum": [ "form", "email", "call", "chat", "api", "agent" ], "description": "How the submission entered the system" }, "source": { "type": "string", "description": "Where the candidate originated (e.g., careerPage, jobBoard, linkedin, talentPool)" }, "type": { "type": "string", "enum": [ "candidate", "talent" ], "description": "Submission type - determines which workflow to trigger" }, "status": { "type": "string", "enum": [ "received", "processing", "processed", "failed", "waiting" ] }, "language": { "type": "string" }, "qualityScore": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Aggregate quality score (1-5 stars) based on answer relevance, clarity, and completeness. AI-generated, recruiter-overridable." }, "fields": { "type": "object", "description": "Form fields keyed by field identifier. Each field contains localized content grouped by language code. Structure: {fieldKey: {langCode: {label, description, value, type, relevance, clarity, completeness, confidence, reasoning}}}." }, "files": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "bucket": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "fileKey": { "type": "string", "description": "S3 key in the submission bucket. The screening workflow reads files.N.fileKey." }, "originalFilename": { "type": "string", "description": "Original filename as uploaded/imported. The screening workflow reads files.N.originalFilename." } } } }, "referral": { "type": "object", "properties": { "referrerName": { "type": "string" }, "referrerEmail": { "type": "string" }, "relationship": { "type": "string" }, "note": { "type": "string" } } }, "consent": { "type": "object", "properties": { "current": { "type": "boolean" }, "future": { "type": "boolean" } } }, "meta": { "type": "object", "description": "Free-form metadata. meta.external carries ATS import correlation ({source, jobShortCode, talentShortCode, applicationShortCode, ttl}); meta.userId is stamped server-side on create. CREATE-ONLY today: the update path ignores meta." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "SubmissionWriteRelationshipsSchema", "type": "object", "description": "WRITE shape for request bodies: the storage-convention plural keys the services and the existing SDK writer classes use. Responses use the wire-shaped RelationshipsSchema instead - the two deliberately differ (PLAN_RELATIONSHIP_CONTRACT.md).", "properties": { "forms": { "title": "SubmissionRelationshipsFormsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "jobs": { "title": "SubmissionRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "talents": { "title": "SubmissionRelationshipsTalentsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "candidates": { "title": "SubmissionRelationshipsCandidatesSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, "required": [ "submissionId", "requestBody" ] } } }, { "type": "function", "function": { "name": "delete_submission", "description": "Delete Submission", "parameters": { "type": "object", "properties": { "submissionId": { "type": "string", "description": "submissionId parameter" }, "permanentDelete": { "type": "string", "description": "Set to true for permanent deletion.", "enum": [ "true", "false" ] } }, "required": [ "submissionId" ] } } }, { "type": "function", "function": { "name": "submission_options", "description": "Submission Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "create_brief", "description": "Create Brief", "parameters": { "title": "CreateBriefRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateBriefRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "briefs" ] }, "attributes": { "title": "BriefAttributesSchema", "type": "object", "required": [ "title" ], "properties": { "title": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Role title. Language-keyed object (keys are locale codes, e.g. en-US, pl-PL)." }, "description": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Brief narrative. Language-keyed object (keys are locale codes, e.g. en-US, pl-PL)." }, "source": { "type": "string", "enum": [ "form", "email", "call", "sms", "ats", "api" ] }, "status": { "type": "string", "enum": [ "received", "processing", "processed", "accepted", "failed" ] }, "language": { "type": "string" }, "location": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Role location. Language-keyed object (keys are locale codes, e.g. en-US, pl-PL)." }, "salary": { "type": "string", "description": "Salary / budget (free text, e.g. '22-26k PLN B2B')" }, "employmentType": { "type": "string", "description": "Employment type (e.g. B2B, employment contract)" }, "seniority": { "type": "string", "description": "Seniority level for the role (e.g. junior, mid, senior)" }, "criteria": { "type": "array", "description": "Recruitment criteria captured from the brief - ordered, tiered ({text: {locale: str}, tier: must|preferred|bonus|disqualifier})", "items": { "title": "BriefCriterionSchema", "type": "object", "properties": { "text": { "type": "object", "description": "Requirement text per locale ({en-US: ..., pl-PL: ...})", "additionalProperties": true }, "tier": { "type": "string", "enum": [ "must", "preferred", "bonus", "disqualifier" ] } } } }, "links": { "type": "array", "description": "Link references captured for the brief (status / finalUrl / markdownS3Key)", "items": { "type": "object" } }, "fields": { "type": "object", "description": "DEPRECATED transitional envelope; content is migrating to top-level fields" }, "files": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "bucket": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" } } } }, "intakeType": { "type": "string", "enum": [ "light", "full" ], "description": "How the brief was built: `full` = the criteria were extracted from\nthe raw intake; `light` = criteria cloned from a baseline job (a\nrecurring role). Drives the intake UI." }, "baseline": { "type": "object", "description": "The baseline job a `light` brief was seeded from (the recurring-role\nsource). Null/absent for `full` briefs.", "additionalProperties": true }, "intakeContext": { "type": "object", "description": "Rich recruiter-facing brief context the PDF/report is built from -\nthe WHO/intent beyond the flat criteria. Every key is best-effort\n(omitted when its source is absent), and the set evolves as the intake\ngrows, so unknown keys MUST be preserved (additionalProperties).\nKnown keys: process, responsibilities, workModel, team, targetMarket.", "additionalProperties": true, "properties": { "process": { "type": "array", "description": "Recruitment pipeline stages and whether each is enabled.", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "enabled": { "type": "boolean" } } } }, "responsibilities": { "type": "object", "description": "Multilingual bullet lists: { locale: [string] }.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "workModel": { "type": "object", "description": "Multilingual work model text: { locale: string }.", "additionalProperties": { "type": "string" } }, "team": { "type": "object", "description": "People + feedback SLA around the role.", "additionalProperties": true, "properties": { "hiringManager": { "type": "string" }, "decisionMaker": { "type": "string" }, "recruiter": { "type": "string" }, "organization": { "type": "string" }, "department": { "type": "object", "description": "Multilingual: { locale: string }.", "additionalProperties": { "type": "string" } }, "sla": { "type": "object", "description": "Multilingual feedback promise: { locale: string }.", "additionalProperties": { "type": "string" } } } }, "targetMarket": { "type": "object", "description": "Multilingual lists per facet: { facet: { locale: [string] } }.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "BriefWriteRelationshipsSchema", "type": "object", "description": "WRITE shape for request bodies: the storage-convention plural keys the services and the existing SDK writer classes use. Responses use the wire-shaped RelationshipsSchema instead - the two deliberately differ (PLAN_RELATIONSHIP_CONTRACT.md).", "properties": { "jobs": { "title": "BriefRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "users": { "title": "BriefRelationshipsUsersSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "list_briefs", "description": "List Briefs", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns briefs with the current status.", "enum": [ "received", "processing", "processed", "failed" ] }, "filterSource": { "type": "string", "description": "Filter briefs by source channel.", "enum": [ "form", "email", "call", "sms", "ats", "api" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "briefs_options", "description": "Briefs Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_brief", "description": "Show Brief", "parameters": { "type": "object", "properties": { "briefId": { "type": "string", "description": "briefId parameter" } }, "required": [ "briefId" ] } } }, { "type": "function", "function": { "name": "update_brief", "description": "Update Brief", "parameters": { "type": "object", "properties": { "briefId": { "type": "string", "description": "briefId parameter" }, "requestBody": { "title": "UpdateBriefRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateBriefRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "briefs" ] }, "id": { "type": "string" }, "attributes": { "title": "BriefAttributesSchema", "type": "object", "required": [ "title" ], "properties": { "title": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Role title. Language-keyed object (keys are locale codes, e.g. en-US, pl-PL)." }, "description": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Brief narrative. Language-keyed object (keys are locale codes, e.g. en-US, pl-PL)." }, "source": { "type": "string", "enum": [ "form", "email", "call", "sms", "ats", "api" ] }, "status": { "type": "string", "enum": [ "received", "processing", "processed", "accepted", "failed" ] }, "language": { "type": "string" }, "location": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Role location. Language-keyed object (keys are locale codes, e.g. en-US, pl-PL)." }, "salary": { "type": "string", "description": "Salary / budget (free text, e.g. '22-26k PLN B2B')" }, "employmentType": { "type": "string", "description": "Employment type (e.g. B2B, employment contract)" }, "seniority": { "type": "string", "description": "Seniority level for the role (e.g. junior, mid, senior)" }, "criteria": { "type": "array", "description": "Recruitment criteria captured from the brief - ordered, tiered ({text: {locale: str}, tier: must|preferred|bonus|disqualifier})", "items": { "title": "BriefCriterionSchema", "type": "object", "properties": { "text": { "type": "object", "description": "Requirement text per locale ({en-US: ..., pl-PL: ...})", "additionalProperties": true }, "tier": { "type": "string", "enum": [ "must", "preferred", "bonus", "disqualifier" ] } } } }, "links": { "type": "array", "description": "Link references captured for the brief (status / finalUrl / markdownS3Key)", "items": { "type": "object" } }, "fields": { "type": "object", "description": "DEPRECATED transitional envelope; content is migrating to top-level fields" }, "files": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "bucket": { "type": "string" }, "name": { "type": "string" }, "contentType": { "type": "string" } } } }, "intakeType": { "type": "string", "enum": [ "light", "full" ], "description": "How the brief was built: `full` = the criteria were extracted from\nthe raw intake; `light` = criteria cloned from a baseline job (a\nrecurring role). Drives the intake UI." }, "baseline": { "type": "object", "description": "The baseline job a `light` brief was seeded from (the recurring-role\nsource). Null/absent for `full` briefs.", "additionalProperties": true }, "intakeContext": { "type": "object", "description": "Rich recruiter-facing brief context the PDF/report is built from -\nthe WHO/intent beyond the flat criteria. Every key is best-effort\n(omitted when its source is absent), and the set evolves as the intake\ngrows, so unknown keys MUST be preserved (additionalProperties).\nKnown keys: process, responsibilities, workModel, team, targetMarket.", "additionalProperties": true, "properties": { "process": { "type": "array", "description": "Recruitment pipeline stages and whether each is enabled.", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "enabled": { "type": "boolean" } } } }, "responsibilities": { "type": "object", "description": "Multilingual bullet lists: { locale: [string] }.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "workModel": { "type": "object", "description": "Multilingual work model text: { locale: string }.", "additionalProperties": { "type": "string" } }, "team": { "type": "object", "description": "People + feedback SLA around the role.", "additionalProperties": true, "properties": { "hiringManager": { "type": "string" }, "decisionMaker": { "type": "string" }, "recruiter": { "type": "string" }, "organization": { "type": "string" }, "department": { "type": "object", "description": "Multilingual: { locale: string }.", "additionalProperties": { "type": "string" } }, "sla": { "type": "object", "description": "Multilingual feedback promise: { locale: string }.", "additionalProperties": { "type": "string" } } } }, "targetMarket": { "type": "object", "description": "Multilingual lists per facet: { facet: { locale: [string] } }.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "BriefWriteRelationshipsSchema", "type": "object", "description": "WRITE shape for request bodies: the storage-convention plural keys the services and the existing SDK writer classes use. Responses use the wire-shaped RelationshipsSchema instead - the two deliberately differ (PLAN_RELATIONSHIP_CONTRACT.md).", "properties": { "jobs": { "title": "BriefRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "users": { "title": "BriefRelationshipsUsersSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, "required": [ "briefId", "requestBody" ] } } }, { "type": "function", "function": { "name": "delete_brief", "description": "Delete Brief", "parameters": { "type": "object", "properties": { "briefId": { "type": "string", "description": "briefId parameter" }, "permanentDelete": { "type": "string", "description": "Set to true for permanent deletion.", "enum": [ "true", "false" ] } }, "required": [ "briefId" ] } } }, { "type": "function", "function": { "name": "brief_options", "description": "Brief Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_browsers", "description": "List Browsers", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns browsers with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_browser", "description": "Create Browser", "parameters": { "title": "CreateBrowserRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateBrowserRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "emails" ] }, "attributes": { "title": "BrowserAttributesSchema", "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "BrowserRelationshipsSchema", "type": "object", "properties": {} } } } } } } }, { "type": "function", "function": { "name": "browsers_options", "description": "Browsers Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_browser", "description": "Show Browser", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_browser", "description": "Update Browser", "parameters": { "title": "UpdateBrowserRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateBrowserRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "emails" ] }, "id": { "type": "string" }, "attributes": { "title": "BrowserAttributesSchema", "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_browser", "description": "Delete Browser", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "browser_options", "description": "Browser Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_calls", "description": "List Calls", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Filter by status bucket. Status IS the folder (email-style):\none value per FE chip nav entry. Accepts single value or\ncomma-separated list (e.g. `incoming,outgoing`). Comma-list\nroutes to the Scan path (slower, no cursor pagination).\nThe granular Twilio status (queued / ringing / no-answer /\nbusy / voicemail) is preserved in `meta.providerStatus` for\nretry / analytics, not exposed as the row status.", "enum": [ "draft", "scheduled", "active", "incoming", "outgoing", "missed", "cancelled", "archived" ] }, "filterDirection": { "type": "string", "description": "Filter by direction (inbound or outbound).", "enum": [ "inbound", "outbound" ] }, "filterProtocol": { "type": "string", "description": "Filter by wire protocol. `phone` is PSTN via Twilio; `webrtc` reserved for the future recruiter Voice SDK.", "enum": [ "phone", "webrtc" ] }, "filterFromIdentifier": { "type": "string", "description": "Filter by caller's protocol-native handle (E.164 phone for PSTN). Indexed via FromIdentifierIndex GSI." }, "filterToIdentifier": { "type": "string", "description": "Filter by callee's protocol-native handle (E.164 phone for PSTN). Indexed via ToIdentifierIndex GSI. Use for 'all calls to this number' views." }, "filterConversationId": { "type": "string", "description": "Filter all calls in a conversation thread. Indexed via ConversationIdIndex GSI." }, "filterIntent": { "type": "string", "description": "Filter by AI intent classifier output (inbound calls only). Post-filtered after pagination - acceptable while intent classification is small-scale.", "enum": [ "brief_request", "job_application", "talent_pool", "status_inquiry", "wrong_number", "sales_chat", "faq", "other" ] }, "include": { "type": "string", "description": "JSON:API `?include=` sideloads. Comma-list of relationship\nslots; each resolved to a per-resource entry in the response\n`included[]` array. Eliminates N+1 lookups for avatars /\nnames. Allowed slots: conversation, candidate, talent, user,\nboeUser, job, brief, schedule. Each included resource carries\n`attributes.name` plus type-specific extras (`avatarUrl` +\n`isBoe` for users, `company` for candidate/talent, `title` +\n`shortCode` for job, `subject` + `type` for conversation,\n`fireAt` + `status` for schedule)." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" }, "sort": { "type": "string", "description": "Sort order. Default `-created` (newest first). Currently\nsupports `-created`, `created`, `-modified`, `modified`. Sort\nby `-startedAt` / `-endedAt` / `-durationSec` deferred until\ncomposite GSIs land - see backend backlog #93.", "enum": [ "-created", "created", "-modified", "modified" ] } } } } }, { "type": "function", "function": { "name": "create_call", "description": "Create Call", "parameters": { "title": "CreateCallRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateCallRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "calls" ] }, "attributes": { "title": "CallAttributesSchema", "type": "object", "description": "Cross-protocol call attributes. Mirror of chat with voice-\nspecific extensions: lifecycle covers provider phases (queued\n-> ringing -> in-progress -> completed) plus the operator\nreview window (draft -> scheduled -> queued). aiMode toggles\nwhether the AI agent is the active speaker, a silent observer,\nor fully off. transcript + summary are multilingual dicts\nmirroring email/chat body shape; the call AI translate Step\nFunction fans them across tenant locales.", "properties": { "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Call direction relative to boe (inbound = caller dialed boe; outbound = boe placed the call)." }, "protocol": { "type": "string", "enum": [ "phone", "webrtc" ], "description": "Wire protocol. Phone is PSTN via Twilio; WebRTC reserves the slot for the future recruiter Voice SDK in the admin web app." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "incoming", "outgoing", "missed", "cancelled", "archived" ], "description": "Lifecycle state - one value per FE chip nav bucket\n(email-style; status IS the folder, no separate folder\nfield). The granular Twilio status (queued / ringing /\nin-progress / no-answer / busy / voicemail / abandoned /\nfailed / Twilio's `canceled`) is preserved on\n`meta.providerStatus` for retry logic and analytics.\n- `draft` - operator editing, no Schedule armed\n- `scheduled` - Schedule armed for fireAt\n- `active` - live (Twilio queued / ringing / in-progress)\n- `incoming` - completed inbound call\n- `outgoing` - completed outbound call\n- `missed` - any failure terminal (no-answer / busy / failed /\n voicemail / abandoned / Twilio's mid-call canceled)\n- `cancelled` - operator-initiated DELETE before dial\n- `archived` - terminal soft-delete" }, "fromIdentifier": { "type": "string", "description": "Caller's protocol-native handle (E.164 phone for PSTN, AAD object id for WebRTC)." }, "fromName": { "type": "string", "description": "Display name of the caller at write time. Denormalised from the resolved principal." }, "fromType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Principal type of the caller." }, "toIdentifier": { "type": "string", "description": "Callee's protocol-native handle." }, "toName": { "type": "string", "description": "Display name of the callee at write time." }, "toType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Principal type of the callee." }, "transcript": { "type": "object", "description": "Multilingual transcript keyed by BCP 47 locale (e.g. {`en-US`: `Hi`, `pl-PL`: `Cześć`}). Source locale is captured first; the AI translate Step Function fills in the rest of the tenant's active locales.", "additionalProperties": { "type": "string" } }, "summary": { "type": "object", "description": "Multilingual post-call summary keyed by BCP 47 locale. LLM-generated after call ends.", "additionalProperties": { "type": "string" } }, "criteriaScoring": { "type": "object", "description": "Per-criterion scoring extracted from the transcript when the call is tied to a job (relationships.job). Map of criterion key -> {score, evidence, confidence}." }, "startedAt": { "type": "string", "description": "ISO 8601 timestamp when the call started (ringing began). Set on outbound dial or inbound webhook arrival." }, "answeredAt": { "type": "string", "description": "ISO 8601 timestamp when the call connected (recipient picked up)." }, "endedAt": { "type": "string", "description": "ISO 8601 timestamp when the call ended (terminal status reached)." }, "durationSec": { "type": "integer", "description": "Call duration in seconds (endedAt - answeredAt)." }, "scheduledFireAt": { "type": "string", "description": "ISO 8601 timestamp at which the Schedule armed for this call will fire and place the outbound dial. Operators can PATCH to reschedule; the eventbus PATCHes the underlying Schedule row in lockstep. Mirror of email/chat scheduledFireAt." }, "scheduleId": { "type": "string", "description": "FK denormalisation of relationships.schedule for cheap read paths." }, "conferenceSid": { "type": "string", "description": "Twilio conference id when the call is a multi-party (3-way) conference. Null for 1:1." }, "isConference": { "type": "boolean", "description": "True when the call is a multi-party conference (recruiter joining via Voice SDK + candidate + boe AI). False for 1:1." }, "aiMode": { "type": "string", "enum": [ "active", "observer", "silent" ], "description": "How the AI agent participates. `active` = AI speaks (default for boe ↔ candidate). `observer` = AI listens, transcribes, surfaces real-time suggestions to the recruiter UI but does not speak. `silent` = recording + post-call analysis only, no AI in the call." }, "plannedTopics": { "type": "array", "description": "List of topic keys the AI agent should cover during the call (e.g. ['salary', 'experience', 'languagesSpoken']). Operator-editable in the review window before fire.", "items": { "type": "string" } }, "systemPrompt": { "type": "string", "description": "Operator-editable agent instructions used as the OpenAI Realtime session's system prompt at fire time. Mirror of email body in the operator review window: edit before fire, the dialed call uses the latest version. Wins over `boeRole`/`boeContext` when both are set." }, "boeRole": { "type": "string", "enum": [ "sales", "interviewer" ], "description": "Prompt template selector. Picks `service/call/container/outbound/prompt/.md` and renders it with `boeContext` placeholders at dial time. `systemPrompt` overrides if also set. Mutually exclusive with `systemPrompt` in effect." }, "boeContext": { "type": "object", "additionalProperties": true, "description": "Placeholder map for the `boeRole` prompt template. Keys depend on the role: for `interviewer` typically `candidateName`, `roleName`, `language`, `applicationUnits`, `employmentOptions`, `nextStepDescription`; for `sales` typically `prospectName`, `prospectCompany`, `language`, `leadSource`. Missing keys render as `not provided`." }, "recording": { "type": "object", "description": "Recording artifacts. Raw G.711 µ-law file is captured live; the audio convert Lambda emits the MP3 derivatives post-call.", "properties": { "type": { "type": "string", "enum": [ "dual-channel", "mixed" ], "description": "Recording layout: dual-channel separates speakers per Twilio leg; mixed is single-track combined." }, "rawUrl": { "type": "string", "description": "S3 URI to the raw G.711 µ-law audio." }, "mixedMp3Url": { "type": "string", "description": "S3 URI to the mixed conversation MP3." }, "humanOnlyMp3Url": { "type": "string", "description": "S3 URI to the human-only MP3 (silent during AI turns)." }, "aiOnlyMp3Url": { "type": "string", "description": "S3 URI to the AI-only MP3 (silent during human turns)." } } }, "languageCode": { "type": "string", "description": "BCP 47 locale of the call (the locale key initially populated in transcript). Detected from the caller's settings or call audio." }, "shortCode": { "type": "string", "description": "Unique short identifier (provider/lookup correlation)." }, "transcriptSegments": { "type": "array", "description": "Structured transcript with timing. Each segment is one turn captured live by the Realtime API. Single shape (NOT translated); text is in `languageCode`. Drives the audio player's clickable speaker timeline.", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "description": "Offset from call start in milliseconds when the speaker began this turn." }, "endMs": { "type": "integer", "description": "Offset from call start in milliseconds when the speaker finished this turn." }, "speakerType": { "type": "string", "enum": [ "ai", "human" ], "description": "Which side spoke this turn." }, "speakerName": { "type": "string", "description": "Display name of the speaker at write time." }, "text": { "type": "string", "description": "What the speaker said, in `languageCode`." } } } }, "speakerStats": { "type": "array", "description": "Per-speaker talk statistics computed once on call finalization. Used by the timeline UI to show talk-time bars.", "items": { "type": "object", "properties": { "speakerType": { "type": "string", "enum": [ "ai", "human" ] }, "speakerName": { "type": "string" }, "talkPercentageBp": { "type": "integer", "description": "Talk-time percentage in basis points (10000 = 100.00%). Integer to avoid float rounding mismatches across clients." } } } }, "keyNotes": { "type": "object", "description": "AI-generated fact bullets per locale, distilled from the transcript.\nKeyed by BCP-47 locale (e.g. `en-US`, `pl-PL`); values are arrays of\nstrings. The source language (matches `languageCode`) is always\npresent; tenant target locales are added by the AI translate step.\nFE selects the locale to render (no auto-flatten on read). Same shape\nas `summary`/`transcript` - one object, NOT separate columns.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "topicsDiscussed": { "type": "array", "description": "Stable facet keys (e.g. `salary`, `experience`, `languagesSpoken`) covered in the call. FE renders via shared `callTopics` dictionary for human-readable labels.", "items": { "type": "string" } }, "sentiment": { "type": "string", "enum": [ "positive", "neutral", "negative", "mixed" ], "description": "AI-derived sentiment of the conversation as a whole." }, "delivery": { "type": "object", "description": "Vocal delivery cues from the audio model (judged from voice, not the\nwords alone). One Map attribute, NOT localized - FE renders each as a\nlabel/meter. Null until the post-call AI Step Function completes.", "properties": { "confidence": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "How composed/assured the candidate sounded." }, "engagement": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Energy / interest level." }, "clarity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "How clearly/structured the candidate spoke." }, "pace": { "type": "string", "enum": [ "slow", "steady", "fast" ], "description": "Speaking speed." } } }, "summaryGeneratedAt": { "type": "string", "description": "ISO 8601 timestamp when the AI summary pipeline (keyNotes + topicsDiscussed + sentiment + summary) finalized. Null until the post-call AI Step Function completes." }, "isLive": { "type": "boolean", "description": "Server-derived: true when status==`active`. Drives the live indicator + polling decision in the UI." }, "hasRecording": { "type": "boolean", "description": "Server-derived: true when recording.mixedMp3Url is present. Lets the list page show a play icon without sending the heavy `recording` block." }, "hasTranscript": { "type": "boolean", "description": "Server-derived: true when transcriptSegments has any entries OR transcript dict has any locale keys. Lets the list page show a transcript icon without sending the heavy `transcript`/`transcriptSegments` payload." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "CallRelationshipsSchema", "type": "object", "description": "Relationship slots on the call resource. Principal slots are\nto-one (`links`, shared URLs, is to-many). Direction\n+ attributes.fromType / toType tell you which side of the\nconversation each principal occupies. Mirror of chat's slot\nset with two voice-specific additions: `job` (call about a\nspecific opening) and `brief` (call collecting / clarifying\na specific brief). `boeUser` is split from `user` so the AI\nagent has a dedicated slot - `user` is reserved for human\ncounterparties (3-way conference recruiter, future user-to-\nuser webapp/Teams chat).", "properties": { "files": { "title": "CallRelationshipsFilesSchema", "description": "File attachments shared on this call (File entities). To-many; container-owns-files.", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "CallRelationshipsFilesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "links": { "title": "CallRelationshipsLinksSchema", "description": "URLs shared during this call, each fetched to markdown (Crawl4AI Link). To-many; container-owns-links.", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "CallRelationshipsLinksDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "conversation": { "title": "CallRelationshipsConversationSchema", "description": "Thread the call belongs to. Phone calls in the same workflow run share a conversation; per-thread queries via ConversationIdIndex.", "type": "object", "properties": { "data": { "title": "CallRelationshipsConversationDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "candidate": { "title": "CallRelationshipsCandidateSchema", "description": "External candidate principal. Set when fromType=candidate (inbound) or toType=candidate (outbound).", "type": "object", "properties": { "data": { "title": "CallRelationshipsCandidateDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "talent": { "title": "CallRelationshipsTalentSchema", "description": "External talent principal. Set when fromType=talent (inbound) or toType=talent (outbound).", "type": "object", "properties": { "data": { "title": "CallRelationshipsTalentDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "user": { "title": "CallRelationshipsUserSchema", "description": "Internal human user (employee). Reserved for 3-way conference recruiters (boe + recruiter + candidate). Today this is typically null on boe-mediated 1:1 calls - the boe AI agent goes in `boeUser`, not here.", "type": "object", "properties": { "data": { "title": "CallRelationshipsUserDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "boeUser": { "title": "CallRelationshipsBoeUserSchema", "description": "Boe AI agent involved in the call. Mirror of tenant.relationships.boeUser - always populated when boe is on the call. Splitting this from the generic `user` slot keeps the semantics clean: `user` is for human counterparties, `boeUser` is the AI agent.", "type": "object", "properties": { "data": { "title": "CallRelationshipsBoeUserDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "job": { "title": "CallRelationshipsJobSchema", "description": "Job opening this call is about. Set on screening calls + phone-brief outbound clarifications targeting a specific opening. Drives criteriaScoring against the job's criteria.", "type": "object", "properties": { "data": { "title": "CallRelationshipsJobDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "brief": { "title": "CallRelationshipsBriefSchema", "description": "Brief this call is collecting / clarifying. Set on phone-brief discovery + clarification calls. Drives the `Calls for brief X` view in the operator UI.", "type": "object", "properties": { "data": { "title": "CallRelationshipsBriefDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "schedule": { "title": "CallRelationshipsScheduleSchema", "description": "Schedule row armed for this call's outbound dial. Set when scheduledFireAt is populated; null on inbound rows or on outbound rows that bypass the review window. Operators reschedule/cancel via PATCH/DELETE on the call resource - the eventbus reflects those changes onto the Schedule row, never the other way around.", "type": "object", "properties": { "data": { "title": "CallRelationshipsScheduleDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } }, "meta": { "title": "CallMetaSchema", "type": "object", "description": "Resource-level meta for call rows. Provider-specific identifiers\nlive here (Twilio CallSid is also surfaced top-level for the\nProviderCallSidIndex GSI; this is the canonical record). Forward-\ncompatible (additionalProperties: true) so transport adapters can\nstash protocol-specific fields without schema churn.", "properties": { "providerCallSid": { "type": "string", "description": "Provider-side call id (Twilio CallSid for phone)." }, "providerStreamSid": { "type": "string", "description": "Provider-side media stream id (Twilio Media Stream SID)." }, "providerStatus": { "type": "string", "description": "Granular provider status, preserved separately from the\nrow's bucket `status`. Drives retry / analytics decisions\n(e.g. `busy` retries faster than `no-answer`; `failed`\ndoesn't retry). Twilio CallStatus values: queued, initiated,\nringing, in-progress, completed, busy, no-answer, failed,\ncanceled." }, "reasonCode": { "type": "string", "enum": [ "call_already_active", "lockout_window", "not_in_review_window" ], "description": "Set on 409 responses for non-actionable transitions. call_already_active=DELETE on active rows; lockout_window=DELETE within 30s of scheduledFireAt; not_in_review_window=PATCH systemPrompt/plannedTopics/scheduledFireAt outside draft|scheduled." }, "intent": { "type": "string", "enum": [ "brief_request", "job_application", "talent_pool", "status_inquiry", "wrong_number", "sales_chat", "faq", "other" ], "description": "AI classifier output, inbound calls only - the fast hangup verdict; the accurate pass reruns on the analyzed transcript (Discover Intent From Call on service:call:analyzed). intent=brief_request opens the phone-brief conversation. Not present on outbound rows." }, "intentReasoning": { "type": "string", "description": "One-sentence explanation of the intent classifier's choice. Inbound calls only." }, "isReply": { "type": "boolean", "description": "True when this call is a workflow-driven follow-up (e.g. boe calling back to clarify a brief)." } }, "additionalProperties": true } } } } } } }, { "type": "function", "function": { "name": "calls_options", "description": "Calls Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_call", "description": "Show Call", "parameters": { "type": "object", "properties": { "include": { "type": "string", "description": "JSON:API `?include=` sideloads. Comma-list of relationship\nslots; each resolved entry is added to the response\n`included[]` array. Allowed slots: conversation, candidate,\ntalent, user, boeUser, job, brief, schedule." } } } } }, { "type": "function", "function": { "name": "update_call", "description": "Update Call", "parameters": { "title": "UpdateCallRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateCallRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "calls" ] }, "id": { "type": "string" }, "attributes": { "title": "CallAttributesSchema", "type": "object", "description": "Cross-protocol call attributes. Mirror of chat with voice-\nspecific extensions: lifecycle covers provider phases (queued\n-> ringing -> in-progress -> completed) plus the operator\nreview window (draft -> scheduled -> queued). aiMode toggles\nwhether the AI agent is the active speaker, a silent observer,\nor fully off. transcript + summary are multilingual dicts\nmirroring email/chat body shape; the call AI translate Step\nFunction fans them across tenant locales.", "properties": { "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Call direction relative to boe (inbound = caller dialed boe; outbound = boe placed the call)." }, "protocol": { "type": "string", "enum": [ "phone", "webrtc" ], "description": "Wire protocol. Phone is PSTN via Twilio; WebRTC reserves the slot for the future recruiter Voice SDK in the admin web app." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "incoming", "outgoing", "missed", "cancelled", "archived" ], "description": "Lifecycle state - one value per FE chip nav bucket\n(email-style; status IS the folder, no separate folder\nfield). The granular Twilio status (queued / ringing /\nin-progress / no-answer / busy / voicemail / abandoned /\nfailed / Twilio's `canceled`) is preserved on\n`meta.providerStatus` for retry logic and analytics.\n- `draft` - operator editing, no Schedule armed\n- `scheduled` - Schedule armed for fireAt\n- `active` - live (Twilio queued / ringing / in-progress)\n- `incoming` - completed inbound call\n- `outgoing` - completed outbound call\n- `missed` - any failure terminal (no-answer / busy / failed /\n voicemail / abandoned / Twilio's mid-call canceled)\n- `cancelled` - operator-initiated DELETE before dial\n- `archived` - terminal soft-delete" }, "fromIdentifier": { "type": "string", "description": "Caller's protocol-native handle (E.164 phone for PSTN, AAD object id for WebRTC)." }, "fromName": { "type": "string", "description": "Display name of the caller at write time. Denormalised from the resolved principal." }, "fromType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Principal type of the caller." }, "toIdentifier": { "type": "string", "description": "Callee's protocol-native handle." }, "toName": { "type": "string", "description": "Display name of the callee at write time." }, "toType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Principal type of the callee." }, "transcript": { "type": "object", "description": "Multilingual transcript keyed by BCP 47 locale (e.g. {`en-US`: `Hi`, `pl-PL`: `Cześć`}). Source locale is captured first; the AI translate Step Function fills in the rest of the tenant's active locales.", "additionalProperties": { "type": "string" } }, "summary": { "type": "object", "description": "Multilingual post-call summary keyed by BCP 47 locale. LLM-generated after call ends.", "additionalProperties": { "type": "string" } }, "criteriaScoring": { "type": "object", "description": "Per-criterion scoring extracted from the transcript when the call is tied to a job (relationships.job). Map of criterion key -> {score, evidence, confidence}." }, "startedAt": { "type": "string", "description": "ISO 8601 timestamp when the call started (ringing began). Set on outbound dial or inbound webhook arrival." }, "answeredAt": { "type": "string", "description": "ISO 8601 timestamp when the call connected (recipient picked up)." }, "endedAt": { "type": "string", "description": "ISO 8601 timestamp when the call ended (terminal status reached)." }, "durationSec": { "type": "integer", "description": "Call duration in seconds (endedAt - answeredAt)." }, "scheduledFireAt": { "type": "string", "description": "ISO 8601 timestamp at which the Schedule armed for this call will fire and place the outbound dial. Operators can PATCH to reschedule; the eventbus PATCHes the underlying Schedule row in lockstep. Mirror of email/chat scheduledFireAt." }, "scheduleId": { "type": "string", "description": "FK denormalisation of relationships.schedule for cheap read paths." }, "conferenceSid": { "type": "string", "description": "Twilio conference id when the call is a multi-party (3-way) conference. Null for 1:1." }, "isConference": { "type": "boolean", "description": "True when the call is a multi-party conference (recruiter joining via Voice SDK + candidate + boe AI). False for 1:1." }, "aiMode": { "type": "string", "enum": [ "active", "observer", "silent" ], "description": "How the AI agent participates. `active` = AI speaks (default for boe ↔ candidate). `observer` = AI listens, transcribes, surfaces real-time suggestions to the recruiter UI but does not speak. `silent` = recording + post-call analysis only, no AI in the call." }, "plannedTopics": { "type": "array", "description": "List of topic keys the AI agent should cover during the call (e.g. ['salary', 'experience', 'languagesSpoken']). Operator-editable in the review window before fire.", "items": { "type": "string" } }, "systemPrompt": { "type": "string", "description": "Operator-editable agent instructions used as the OpenAI Realtime session's system prompt at fire time. Mirror of email body in the operator review window: edit before fire, the dialed call uses the latest version. Wins over `boeRole`/`boeContext` when both are set." }, "boeRole": { "type": "string", "enum": [ "sales", "interviewer" ], "description": "Prompt template selector. Picks `service/call/container/outbound/prompt/.md` and renders it with `boeContext` placeholders at dial time. `systemPrompt` overrides if also set. Mutually exclusive with `systemPrompt` in effect." }, "boeContext": { "type": "object", "additionalProperties": true, "description": "Placeholder map for the `boeRole` prompt template. Keys depend on the role: for `interviewer` typically `candidateName`, `roleName`, `language`, `applicationUnits`, `employmentOptions`, `nextStepDescription`; for `sales` typically `prospectName`, `prospectCompany`, `language`, `leadSource`. Missing keys render as `not provided`." }, "recording": { "type": "object", "description": "Recording artifacts. Raw G.711 µ-law file is captured live; the audio convert Lambda emits the MP3 derivatives post-call.", "properties": { "type": { "type": "string", "enum": [ "dual-channel", "mixed" ], "description": "Recording layout: dual-channel separates speakers per Twilio leg; mixed is single-track combined." }, "rawUrl": { "type": "string", "description": "S3 URI to the raw G.711 µ-law audio." }, "mixedMp3Url": { "type": "string", "description": "S3 URI to the mixed conversation MP3." }, "humanOnlyMp3Url": { "type": "string", "description": "S3 URI to the human-only MP3 (silent during AI turns)." }, "aiOnlyMp3Url": { "type": "string", "description": "S3 URI to the AI-only MP3 (silent during human turns)." } } }, "languageCode": { "type": "string", "description": "BCP 47 locale of the call (the locale key initially populated in transcript). Detected from the caller's settings or call audio." }, "shortCode": { "type": "string", "description": "Unique short identifier (provider/lookup correlation)." }, "transcriptSegments": { "type": "array", "description": "Structured transcript with timing. Each segment is one turn captured live by the Realtime API. Single shape (NOT translated); text is in `languageCode`. Drives the audio player's clickable speaker timeline.", "items": { "type": "object", "properties": { "startMs": { "type": "integer", "description": "Offset from call start in milliseconds when the speaker began this turn." }, "endMs": { "type": "integer", "description": "Offset from call start in milliseconds when the speaker finished this turn." }, "speakerType": { "type": "string", "enum": [ "ai", "human" ], "description": "Which side spoke this turn." }, "speakerName": { "type": "string", "description": "Display name of the speaker at write time." }, "text": { "type": "string", "description": "What the speaker said, in `languageCode`." } } } }, "speakerStats": { "type": "array", "description": "Per-speaker talk statistics computed once on call finalization. Used by the timeline UI to show talk-time bars.", "items": { "type": "object", "properties": { "speakerType": { "type": "string", "enum": [ "ai", "human" ] }, "speakerName": { "type": "string" }, "talkPercentageBp": { "type": "integer", "description": "Talk-time percentage in basis points (10000 = 100.00%). Integer to avoid float rounding mismatches across clients." } } } }, "keyNotes": { "type": "object", "description": "AI-generated fact bullets per locale, distilled from the transcript.\nKeyed by BCP-47 locale (e.g. `en-US`, `pl-PL`); values are arrays of\nstrings. The source language (matches `languageCode`) is always\npresent; tenant target locales are added by the AI translate step.\nFE selects the locale to render (no auto-flatten on read). Same shape\nas `summary`/`transcript` - one object, NOT separate columns.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "topicsDiscussed": { "type": "array", "description": "Stable facet keys (e.g. `salary`, `experience`, `languagesSpoken`) covered in the call. FE renders via shared `callTopics` dictionary for human-readable labels.", "items": { "type": "string" } }, "sentiment": { "type": "string", "enum": [ "positive", "neutral", "negative", "mixed" ], "description": "AI-derived sentiment of the conversation as a whole." }, "delivery": { "type": "object", "description": "Vocal delivery cues from the audio model (judged from voice, not the\nwords alone). One Map attribute, NOT localized - FE renders each as a\nlabel/meter. Null until the post-call AI Step Function completes.", "properties": { "confidence": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "How composed/assured the candidate sounded." }, "engagement": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Energy / interest level." }, "clarity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "How clearly/structured the candidate spoke." }, "pace": { "type": "string", "enum": [ "slow", "steady", "fast" ], "description": "Speaking speed." } } }, "summaryGeneratedAt": { "type": "string", "description": "ISO 8601 timestamp when the AI summary pipeline (keyNotes + topicsDiscussed + sentiment + summary) finalized. Null until the post-call AI Step Function completes." }, "isLive": { "type": "boolean", "description": "Server-derived: true when status==`active`. Drives the live indicator + polling decision in the UI." }, "hasRecording": { "type": "boolean", "description": "Server-derived: true when recording.mixedMp3Url is present. Lets the list page show a play icon without sending the heavy `recording` block." }, "hasTranscript": { "type": "boolean", "description": "Server-derived: true when transcriptSegments has any entries OR transcript dict has any locale keys. Lets the list page show a transcript icon without sending the heavy `transcript`/`transcriptSegments` payload." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_call", "description": "Delete Call", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "call_options", "description": "Call Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "dial_call", "description": "Dial Call", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "dial_call_options", "description": "Dial Call Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_comments", "description": "List Comments", "parameters": { "type": "object", "properties": { "filterTargetType": { "type": "string", "description": "Limit to comments on this resource type. Pair with filterTargetId.", "enum": [ "calls", "chats", "emails", "candidates", "jobs", "talents", "briefs", "tasks" ] }, "filterTargetId": { "type": "string", "description": "Limit to comments on this specific target id. Requires filterTargetType." }, "filterAuthorId": { "type": "string", "description": "Limit to comments authored by this user. Indexed via AuthorIndex." }, "filterIsResolved": { "type": "boolean", "description": "Filter by `isResolved` flag (true/false). Post-filtered after pagination - acceptable while resolution is rare." }, "include": { "type": "string", "description": "JSON:API sideload. Currently supports `author` (resolves to the user row with name + avatarUrl + isBoe)." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" }, "sort": { "type": "string", "description": "Sort order. Default `-created` (newest first).", "enum": [ "-created", "created", "-modified", "modified" ] } } } } }, { "type": "function", "function": { "name": "create_comment", "description": "Create Comment", "parameters": { "title": "CreateCommentRequestSchema", "type": "object", "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "comments" ] }, "attributes": { "type": "object", "required": [ "body", "targetType", "targetId" ], "properties": { "body": { "type": "string", "maxLength": 5000 }, "targetType": { "type": "string", "enum": [ "calls", "chats", "emails", "candidates", "jobs", "talents", "briefs", "tasks" ] }, "targetId": { "type": "string" }, "parentCommentId": { "type": "string" }, "mentionedUserIds": { "type": "array", "items": { "type": "string" } }, "isResolved": { "type": "boolean" } } } } } } } } }, { "type": "function", "function": { "name": "show_comment", "description": "Show Comment", "parameters": { "type": "object", "properties": { "include": { "type": "string", "description": "JSON:API sideload. `author` resolves the user row." } } } } }, { "type": "function", "function": { "name": "update_comment", "description": "Update Comment", "parameters": { "title": "UpdateCommentRequestSchema", "type": "object", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "comments" ] }, "id": { "type": "string" }, "attributes": { "type": "object", "description": "Patchable fields. Only `body`, `isResolved`, and `mentionedUserIds` are editable. Edit by author OR tenant admin/owner; others get 403.", "properties": { "body": { "type": "string", "maxLength": 5000 }, "isResolved": { "type": "boolean" }, "mentionedUserIds": { "type": "array", "items": { "type": "string" } } } } } } } } } }, { "type": "function", "function": { "name": "delete_comment", "description": "Delete Comment", "parameters": { "type": "object", "properties": { "permanentDelete": { "type": "string", "description": "Set to `true` for hard-delete. Default is soft-delete (status=archived).", "enum": [ "true", "false" ] } } } } }, { "type": "function", "function": { "name": "list_chats", "description": "List Chats", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns chats with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterSenderNumber": { "type": "string", "description": "Filter chats by sender phone number (e.g. +48535517222)." }, "filterConversationId": { "type": "string", "description": "Returns all chat rows belonging to one conversation (thread).\nUsed by the chat web app's thread view to render messages\nchronologically. Backed by ConversationIdIndex GSI." }, "sort": { "type": "string", "description": "Sort order. `created` for oldest-first, `-created` for newest-first.\nUse `created` for thread views (oldest-first message rendering)." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_chat", "description": "Create Chat", "parameters": { "title": "CreateChatRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateChatRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "chats" ] }, "attributes": { "title": "ChatAttributesSchema", "type": "object", "description": "Cross-protocol chat message attributes. One row per direction:\ninbound and outbound replies on the same conversation are separate\nrows, joined by relationships.conversation. `protocol` is the wire\nformat (sms/whatsapp/teams/googlechat/webapp). `fromIdentifier`\nand `toIdentifier` are protocol-native handles (E.164 phone for\nSMS/WhatsApp, Teams AAD object id, Google Chat user id, etc.) so\nthe row carries the literal sender/receiver without joins. The\nresolved principals (candidate / talent / user) live in\nrelationships - direction tells you which side of the\nconversation each principal is on (inbound: from-side is the\nexternal party; outbound: to-side is the external party, plus an\noptional user relationship for the boe agent that signed it).\n`body` is a multilingual dict {locale: text} mirroring the email\npattern - the chat AI step function translates user-facing\ncontent into the tenant's active locales for admin display.", "properties": { "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Message direction relative to boe (inbound from external, outbound to external)." }, "protocol": { "type": "string", "enum": [ "sms", "whatsapp", "teams", "googlechat", "webapp" ], "description": "Wire protocol. Adapter Lambdas set this on write so downstream code can branch on rendering / status callback handling." }, "fromIdentifier": { "type": "string", "description": "Sender's protocol-native handle (E.164 phone for SMS/WhatsApp, AAD object id for Teams, etc.)." }, "fromName": { "type": "string", "description": "Display name of the sender at write time. Denormalised from the resolved principal." }, "fromType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Principal type of the sender. Maps the platform's principal tables. `guest` for unknown senders (typically rejected by the inbound gate)." }, "toIdentifier": { "type": "string", "description": "Recipient's protocol-native handle." }, "toName": { "type": "string", "description": "Display name of the recipient at write time." }, "toType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Principal type of the recipient." }, "body": { "type": "object", "description": "Multilingual message body keyed by BCP 47 locale (e.g. {`en-US`: `Hi`, `pl-PL`: `Cześć`}). Inbound writers stamp a single locale; the chat AI step function fills the rest.", "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "received", "draft", "scheduled", "cancelled", "queued", "sent", "delivered", "failed", "archived" ], "description": "Lifecycle state. Inbound rows go straight to `received`. Outbound rows that go through an operator review window or explicit scheduling start at `draft` (editable) or `scheduled` (Schedule armed for fireAt); on Schedule fire they progress queued -> sent -> delivered (or failed). `cancelled` is the terminal state when an operator hard-killed a draft / scheduled row before fire. `archived` is a terminal soft-delete for both directions." }, "scheduledFireAt": { "type": "string", "description": "ISO 8601 timestamp at which the Schedule row armed for this chat will fire. Set on direction=outbound rows that go through a review window or explicit scheduling. Operators can PATCH this to reschedule; the eventbus PATCHes the underlying Schedule row in lockstep. Mirror of email.attributes.scheduledFireAt." }, "scheduleId": { "type": "string", "description": "FK denormalisation of relationships.schedule for cheap read paths. Populated by the chat eventbus after it arms a Schedule row in response to chat:created with scheduledFireAt set. Mirror of email.attributes.scheduleId." }, "languageCode": { "type": "string", "description": "BCP 47 locale of the original message (the locale key initially populated in `body`). Detected at the inbound gate, set by the writer on outbound." }, "shortCode": { "type": "string", "description": "Unique short identifier (provider/lookup correlation)." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "ChatRelationshipsSchema", "type": "object", "description": "Relationship slots for a chat row. Principal slots are to-one\n(`links`, shared URLs, is to-many). Direction +\nattributes.fromType / toType tell you which side of the\nconversation each principal is on - we don't duplicate that\ninto directional relationship names. For boe-mediated flows\nat most two of {user, candidate, talent} are populated per\nrow: the external party (candidate or talent) and, on outbound,\nthe boe user that signed the message.", "properties": { "files": { "title": "ChatRelationshipsFilesSchema", "description": "File attachments sent in this chat (File entities). To-many; container-owns-files.", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "ChatRelationshipsFilesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "links": { "title": "ChatRelationshipsLinksSchema", "description": "URLs shared in this chat, each fetched to markdown (Crawl4AI Link). To-many; container-owns-links.", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "ChatRelationshipsLinksDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "conversation": { "title": "ChatRelationshipsConversationSchema", "description": "Thread the chat row belongs to. SMS replies on the same boe\nnumber share a conversation; the workflow engine parks runs\non the conversation's meta and reads parkedRunContext to\nresume on inbound. The conversation id is denormalised onto\nthe chat row's internal `conversationId` attribute (indexed\nby ConversationIdIndex) for cheap per-thread history queries\n- API consumers should read it from this relationship, not\nfrom attributes.", "type": "object", "properties": { "data": { "title": "ChatRelationshipsConversationDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "candidate": { "title": "ChatRelationshipsCandidateSchema", "description": "External candidate principal. Set when fromType=candidate (inbound) or toType=candidate (outbound).", "type": "object", "properties": { "data": { "title": "ChatRelationshipsCandidateDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "talent": { "title": "ChatRelationshipsTalentSchema", "description": "External talent principal. Set when fromType=talent (inbound) or toType=talent (outbound).", "type": "object", "properties": { "data": { "title": "ChatRelationshipsTalentDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "user": { "title": "ChatRelationshipsUserSchema", "description": "Internal human user (employee). Reserved for user-to-user webapp/Teams chat counterparties. Today this is typically null - boe-signed outbound rows put the boe AI in `boeUser`, not here.", "type": "object", "properties": { "data": { "title": "ChatRelationshipsUserDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "boeUser": { "title": "ChatRelationshipsBoeUserSchema", "description": "Boe AI agent involved in this message. Mirror of tenant.relationships.boeUser - always populated when boe is on either side of the conversation (today: every row). Splitting this from the generic `user` slot keeps the semantics clean: `user` is for human counterparties, `boeUser` is the AI agent.", "type": "object", "properties": { "data": { "title": "ChatRelationshipsBoeUserDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "schedule": { "title": "ChatRelationshipsScheduleSchema", "description": "Schedule row armed for this chat's outbound dispatch. Set when scheduledFireAt is populated; null on inbound rows or on outbound rows that bypass the review window. Operators reschedule/cancel via PATCH/DELETE on the chat resource - the eventbus reflects those changes onto the Schedule row, never the other way around.", "type": "object", "properties": { "data": { "title": "ChatRelationshipsScheduleDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } }, "meta": { "type": "object", "additionalProperties": true } } } } } } }, { "type": "function", "function": { "name": "chats_options", "description": "Chats Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_chat", "description": "Show Chat", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_chat", "description": "Update Chat", "parameters": { "title": "UpdateChatRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateChatRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "chats" ] }, "id": { "type": "string" }, "attributes": { "title": "ChatAttributesSchema", "type": "object", "description": "Cross-protocol chat message attributes. One row per direction:\ninbound and outbound replies on the same conversation are separate\nrows, joined by relationships.conversation. `protocol` is the wire\nformat (sms/whatsapp/teams/googlechat/webapp). `fromIdentifier`\nand `toIdentifier` are protocol-native handles (E.164 phone for\nSMS/WhatsApp, Teams AAD object id, Google Chat user id, etc.) so\nthe row carries the literal sender/receiver without joins. The\nresolved principals (candidate / talent / user) live in\nrelationships - direction tells you which side of the\nconversation each principal is on (inbound: from-side is the\nexternal party; outbound: to-side is the external party, plus an\noptional user relationship for the boe agent that signed it).\n`body` is a multilingual dict {locale: text} mirroring the email\npattern - the chat AI step function translates user-facing\ncontent into the tenant's active locales for admin display.", "properties": { "direction": { "type": "string", "enum": [ "inbound", "outbound" ], "description": "Message direction relative to boe (inbound from external, outbound to external)." }, "protocol": { "type": "string", "enum": [ "sms", "whatsapp", "teams", "googlechat", "webapp" ], "description": "Wire protocol. Adapter Lambdas set this on write so downstream code can branch on rendering / status callback handling." }, "fromIdentifier": { "type": "string", "description": "Sender's protocol-native handle (E.164 phone for SMS/WhatsApp, AAD object id for Teams, etc.)." }, "fromName": { "type": "string", "description": "Display name of the sender at write time. Denormalised from the resolved principal." }, "fromType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Principal type of the sender. Maps the platform's principal tables. `guest` for unknown senders (typically rejected by the inbound gate)." }, "toIdentifier": { "type": "string", "description": "Recipient's protocol-native handle." }, "toName": { "type": "string", "description": "Display name of the recipient at write time." }, "toType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Principal type of the recipient." }, "body": { "type": "object", "description": "Multilingual message body keyed by BCP 47 locale (e.g. {`en-US`: `Hi`, `pl-PL`: `Cześć`}). Inbound writers stamp a single locale; the chat AI step function fills the rest.", "additionalProperties": { "type": "string" } }, "status": { "type": "string", "enum": [ "received", "draft", "scheduled", "cancelled", "queued", "sent", "delivered", "failed", "archived" ], "description": "Lifecycle state. Inbound rows go straight to `received`. Outbound rows that go through an operator review window or explicit scheduling start at `draft` (editable) or `scheduled` (Schedule armed for fireAt); on Schedule fire they progress queued -> sent -> delivered (or failed). `cancelled` is the terminal state when an operator hard-killed a draft / scheduled row before fire. `archived` is a terminal soft-delete for both directions." }, "scheduledFireAt": { "type": "string", "description": "ISO 8601 timestamp at which the Schedule row armed for this chat will fire. Set on direction=outbound rows that go through a review window or explicit scheduling. Operators can PATCH this to reschedule; the eventbus PATCHes the underlying Schedule row in lockstep. Mirror of email.attributes.scheduledFireAt." }, "scheduleId": { "type": "string", "description": "FK denormalisation of relationships.schedule for cheap read paths. Populated by the chat eventbus after it arms a Schedule row in response to chat:created with scheduledFireAt set. Mirror of email.attributes.scheduleId." }, "languageCode": { "type": "string", "description": "BCP 47 locale of the original message (the locale key initially populated in `body`). Detected at the inbound gate, set by the writer on outbound." }, "shortCode": { "type": "string", "description": "Unique short identifier (provider/lookup correlation)." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_chat", "description": "Delete Chat", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "chat_options", "description": "Chat Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_personas", "description": "List Personas", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns personas with this status. Defaults to `active`, which is\nthe only status a persona may be CONSUMED in. `draft` is the\nhonest in-between: the cohort exists and the profile is being\nsynthesized, but it is under the k-anonymity threshold (fewer\nthan three hires), so nothing scores or writes copy against it.\nRecruiters should be able to see that a market is building, so\nthe list has to be able to return it.", "enum": [ "active", "draft", "archived" ] }, "filterScopeKey": { "type": "string", "description": "Returns the persona for one position family in one market.\nFormat `{positionFamily}#{scope}`, where scope is\n`city:`, `voivodeship:`, `country:` or\n`remote` - for example\n`regional-sales-representative#city:krakow`. Slugs are folded\n(lowercase, no diacritics), so Krakow and Kraków are one key." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_persona", "description": "Create Persona", "parameters": { "title": "CreatePersonaRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreatePersonaRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "emails" ] }, "attributes": { "title": "PersonaAttributesSchema", "type": "object", "description": "A persona is a REGIONAL COHORT profile, not a person: it is\nsynthesized from the talents this tenant actually hired for one\nposition family in one market. Nothing here describes an individual,\nand `name` / `profilePictureUrl` are an invented label for the\ncohort, never a real person.", "properties": { "status": { "type": "string", "description": "Only `active` personas may be shown as a benchmark - see\n`memberCount`. Everything else is a work in progress.", "enum": [ "active", "inactive", "draft", "pending", "archived", "failed" ] }, "source": { "type": "string" }, "name": { "type": "object", "description": "Language-keyed invented name for the archetype. Stable across\nrebuilds, but regenerated when the cohort's predominant gender\nflips - the name states a gender, and that gender is a finding\nabout the cohort (see `identityGender`).", "additionalProperties": true }, "identityGender": { "type": "string", "description": "The cohort gender the current name and picture were minted for. Diagnostic.", "enum": [ "male", "female" ] }, "profilePictureUrl": { "type": "string", "description": "Illustration for the archetype. Not a photograph of anyone." }, "gender": { "type": "object", "description": "Language-keyed, cohort-derived. Locale value unconstrained (Any).", "additionalProperties": true }, "ageRange": { "type": "object", "description": "Language-keyed, cohort-derived. Locale value unconstrained (Any).", "additionalProperties": true }, "scope": { "type": "object", "description": "Which market this persona describes: `{level: city|voivodeship|\ncountry|remote, city?, voivodeship?, country?}`. A hire feeds\nthree personas (city, voivodeship, country), and consumers take\nthe most specific USABLE one.", "additionalProperties": true }, "scopeKey": { "type": "string", "description": "`{positionFamily}#{scope}` - the list filter (`filterScopeKey`) and the index key." }, "positionFamily": { "type": "string", "description": "Slug of the role the cohort was hired for, e.g. `regional-sales-representative`." }, "memberCount": { "type": "integer", "description": "How many hired talents the cohort holds. Below 3 the profile is\nthose few people in disguise, so it is never published and never\nconsumed - k-anonymity, not a display preference." }, "cohortRead": { "type": "integer", "description": "How many members actually fed the profile on this row (diagnostic; can be lower than memberCount)." }, "provenCount": { "type": "integer", "description": "How many cohort members the hiring manager CONFIRMED at the\n90-day probation mark. \"3 hires, 2 proven\" is the number that\nturns the persona from \"whom we hired\" into \"who worked out\".\nCounted in code, never by a model." }, "talentCount": { "type": "integer", "description": "Legacy mirror of memberCount." }, "version": { "type": "integer", "description": "Bumped by every rebuild that wrote something." }, "publishedAt": { "type": "string", "description": "When this persona last became consumable." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "availability": { "type": "object", "description": "Language-keyed availability pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "certifications": { "type": "object", "description": "Language-keyed certifications pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "companyTypeExperience": { "type": "object", "description": "Language-keyed companyTypeExperience pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "education": { "type": "object", "description": "Language-keyed education pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "experienceAndSeniority": { "type": "object", "description": "Language-keyed experienceAndSeniority pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "industryExperience": { "type": "object", "description": "Language-keyed industryExperience pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "jobPositions": { "type": "object", "description": "Language-keyed jobPositions pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "jobTendencies": { "type": "object", "description": "Language-keyed jobTendencies pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "languagesSpoken": { "type": "object", "description": "Language-keyed languagesSpoken pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "licenses": { "type": "object", "description": "Language-keyed licenses pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "locationPreferences": { "type": "object", "description": "Language-keyed locationPreferences pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "personalityAndSoftSkills": { "type": "object", "description": "Language-keyed personalityAndSoftSkills pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "salaryExpectation": { "type": "object", "description": "Language-keyed salaryExpectation pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "skillsAndExpertise": { "type": "object", "description": "Language-keyed skillsAndExpertise pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "workAuthorization": { "type": "object", "description": "Language-keyed workAuthorization pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "workPreferences": { "type": "object", "description": "Language-keyed workPreferences pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "responsibilities": { "type": "object", "description": "Language-keyed responsibilities pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "hobbiesAndInterests": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "personalTraits": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "goalsAndAspirations": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "mainFrustrations": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "keyCompetenciesAndStrengths": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "quickInsights": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "keywords": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true } } }, "relationships": { "title": "PersonaRelationshipsSchema", "type": "object", "description": "Cohort MEMBERSHIP is never exposed: the `talents` relationship (the\nhired people behind the aggregate) is stripped from every response -\nthe persona is an aggregate of at least three people, and listing\nthem would undo exactly that.", "properties": { "user": { "title": "PersonaRelationshipsUserSchema", "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "jobs": { "title": "PersonaRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "PersonaRelationshipsJobsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "candidates": { "title": "PersonaRelationshipsCandidatesSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "PersonaRelationshipsCandidatesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "operations": { "title": "PersonaRelationshipsOperationsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "PersonaRelationshipsOperationsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "personas_options", "description": "Personas Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_persona", "description": "Show Persona", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_persona", "description": "Update Persona", "parameters": { "title": "UpdatePersonaRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdatePersonaRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "emails" ] }, "id": { "type": "string" }, "attributes": { "title": "PersonaAttributesSchema", "type": "object", "description": "A persona is a REGIONAL COHORT profile, not a person: it is\nsynthesized from the talents this tenant actually hired for one\nposition family in one market. Nothing here describes an individual,\nand `name` / `profilePictureUrl` are an invented label for the\ncohort, never a real person.", "properties": { "status": { "type": "string", "description": "Only `active` personas may be shown as a benchmark - see\n`memberCount`. Everything else is a work in progress.", "enum": [ "active", "inactive", "draft", "pending", "archived", "failed" ] }, "source": { "type": "string" }, "name": { "type": "object", "description": "Language-keyed invented name for the archetype. Stable across\nrebuilds, but regenerated when the cohort's predominant gender\nflips - the name states a gender, and that gender is a finding\nabout the cohort (see `identityGender`).", "additionalProperties": true }, "identityGender": { "type": "string", "description": "The cohort gender the current name and picture were minted for. Diagnostic.", "enum": [ "male", "female" ] }, "profilePictureUrl": { "type": "string", "description": "Illustration for the archetype. Not a photograph of anyone." }, "gender": { "type": "object", "description": "Language-keyed, cohort-derived. Locale value unconstrained (Any).", "additionalProperties": true }, "ageRange": { "type": "object", "description": "Language-keyed, cohort-derived. Locale value unconstrained (Any).", "additionalProperties": true }, "scope": { "type": "object", "description": "Which market this persona describes: `{level: city|voivodeship|\ncountry|remote, city?, voivodeship?, country?}`. A hire feeds\nthree personas (city, voivodeship, country), and consumers take\nthe most specific USABLE one.", "additionalProperties": true }, "scopeKey": { "type": "string", "description": "`{positionFamily}#{scope}` - the list filter (`filterScopeKey`) and the index key." }, "positionFamily": { "type": "string", "description": "Slug of the role the cohort was hired for, e.g. `regional-sales-representative`." }, "memberCount": { "type": "integer", "description": "How many hired talents the cohort holds. Below 3 the profile is\nthose few people in disguise, so it is never published and never\nconsumed - k-anonymity, not a display preference." }, "cohortRead": { "type": "integer", "description": "How many members actually fed the profile on this row (diagnostic; can be lower than memberCount)." }, "provenCount": { "type": "integer", "description": "How many cohort members the hiring manager CONFIRMED at the\n90-day probation mark. \"3 hires, 2 proven\" is the number that\nturns the persona from \"whom we hired\" into \"who worked out\".\nCounted in code, never by a model." }, "talentCount": { "type": "integer", "description": "Legacy mirror of memberCount." }, "version": { "type": "integer", "description": "Bumped by every rebuild that wrote something." }, "publishedAt": { "type": "string", "description": "When this persona last became consumable." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } }, "availability": { "type": "object", "description": "Language-keyed availability pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "certifications": { "type": "object", "description": "Language-keyed certifications pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "companyTypeExperience": { "type": "object", "description": "Language-keyed companyTypeExperience pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "education": { "type": "object", "description": "Language-keyed education pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "experienceAndSeniority": { "type": "object", "description": "Language-keyed experienceAndSeniority pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "industryExperience": { "type": "object", "description": "Language-keyed industryExperience pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "jobPositions": { "type": "object", "description": "Language-keyed jobPositions pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "jobTendencies": { "type": "object", "description": "Language-keyed jobTendencies pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "languagesSpoken": { "type": "object", "description": "Language-keyed languagesSpoken pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "licenses": { "type": "object", "description": "Language-keyed licenses pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "locationPreferences": { "type": "object", "description": "Language-keyed locationPreferences pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "personalityAndSoftSkills": { "type": "object", "description": "Language-keyed personalityAndSoftSkills pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "salaryExpectation": { "type": "object", "description": "Language-keyed salaryExpectation pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "skillsAndExpertise": { "type": "object", "description": "Language-keyed skillsAndExpertise pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "workAuthorization": { "type": "object", "description": "Language-keyed workAuthorization pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "workPreferences": { "type": "object", "description": "Language-keyed workPreferences pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "responsibilities": { "type": "object", "description": "Language-keyed responsibilities pattern across the cohort. Each entry carries its own prevalence (\"N of M hired talents\").", "additionalProperties": true }, "hobbiesAndInterests": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "personalTraits": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "goalsAndAspirations": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "mainFrustrations": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "keyCompetenciesAndStrengths": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "quickInsights": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true }, "keywords": { "type": "object", "description": "Language-keyed narrative synthesis. Locale value unconstrained (Any) - see the candidate schema note.", "additionalProperties": true } } } } } } } } }, { "type": "function", "function": { "name": "delete_persona", "description": "Delete Persona", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "persona_options", "description": "Persona Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_notes", "description": "List Notes", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns notes with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_note", "description": "Create Note", "parameters": { "title": "CreateNoteRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateNoteRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "notes" ] }, "attributes": { "title": "NoteAttributesSchema", "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Multilingual note details keyed by language code" }, "source": { "type": "string", "description": "Source of the note" }, "authorUserId": { "type": "string", "description": "Denormalized user id of the note's author (mirror of email.fromUserId): the boe workflow user for AI-written notes, the human creator for manual ones. Server-stamped at create from the caller identity; FE joins against its local user cache to render name + avatar without a per-row API call. Null on legacy rows." }, "ttl": { "type": "string", "description": "Time-to-live expiration timestamp" }, "meta": { "type": "object", "additionalProperties": true }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "NoteRelationshipsSchema", "type": "object", "properties": { "candidate": { "title": "NoteRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "title": "NoteRelationshipsCandidateDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "report": { "title": "NoteRelationshipsReportSchema", "type": "object", "properties": { "data": { "title": "NoteRelationshipsReportDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "operation": { "title": "NoteRelationshipsOperationSchema", "type": "object", "properties": { "data": { "title": "NoteRelationshipsOperationDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "notes_options", "description": "Notes Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_note", "description": "Show Note", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_note", "description": "Update Note", "parameters": { "title": "UpdateNoteRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateNoteRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "notes" ] }, "id": { "type": "string" }, "attributes": { "title": "NoteAttributesSchema", "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "details": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Multilingual note details keyed by language code" }, "source": { "type": "string", "description": "Source of the note" }, "authorUserId": { "type": "string", "description": "Denormalized user id of the note's author (mirror of email.fromUserId): the boe workflow user for AI-written notes, the human creator for manual ones. Server-stamped at create from the caller identity; FE joins against its local user cache to render name + avatar without a per-row API call. Null on legacy rows." }, "ttl": { "type": "string", "description": "Time-to-live expiration timestamp" }, "meta": { "type": "object", "additionalProperties": true }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_note", "description": "Delete Note", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "note_options", "description": "Note Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_states", "description": "List States", "parameters": { "type": "object", "properties": { "filterResourceType": { "type": "string", "description": "Only return states for this resource type.", "enum": [ "emails", "chats", "calls", "comments", "candidates", "conversations", "jobs", "talents", "personas", "reports", "tasks" ] }, "filterResourceIds": { "type": "string", "description": "Comma-separated list of resource ids to batch-fetch. Requires `filterResourceType`." }, "folder": { "type": "string", "description": "Folder-style filter. Tagged-union: the fixed folders are an enum,\nand the label folder is a `label:` template. Orthogonal\nto filterResourceType and filterResourceIds which scope within\nthe folder.\n\nFixed folders:\n `all` - default, no folder filter\n `unseen` - only unread rows (sparse UnseenIndex)\n `starred` - only starred rows (sparse StarredIndex)\n `spam` - only user-spam-marked rows (sparse SpamIndex)\n\nLabel folder:\n `label:` - rows whose `flags.labels` contains labelId\n\nTypeScript callers should narrow this to\n`'all' | 'unseen' | 'starred' | 'spam' | \\`label:${string}\\``\nin their client wrapper; OpenAPI cannot express template-literal\nunions natively." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_state", "description": "Upsert State", "parameters": { "title": "CreateStateRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateStateRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "states" ] }, "attributes": { "title": "StateAttributesSchema", "type": "object", "properties": { "userId": { "type": "string", "description": "Owner of this state row. Always the authenticated user; never set by the client." }, "resourceType": { "type": "string", "enum": [ "emails", "chats", "candidates", "conversations", "jobs", "talents", "personas", "reports", "tasks" ], "description": "The kind of resource this state describes. Lives in the composite id as `{resourceType}:{resourceId}`." }, "resourceId": { "type": "string", "description": "Id of the resource this state describes (e.g. an emailId, candidateId)." }, "isSeen": { "type": "boolean", "description": "True if the user has opened the resource at least once. Derived from the presence of `seenAt`; clients can write either `isSeen` or `seenAt` on upsert." }, "isStarred": { "type": "boolean", "description": "True if the user has starred/favourited the resource." }, "isSpam": { "type": "boolean", "description": "True if the user marked this resource as spam. Distinct from the email service's `suppressed` status, which is SES-driven on outbound delivery; this is an inbound, per-user action." }, "seenAt": { "type": "string", "description": "ISO 8601 timestamp of the user's most recent open. Absent means never seen." }, "starredAt": { "type": "string", "description": "ISO 8601 timestamp of when the user starred the resource. Absent means not starred; used as the sort key for the `Starred` folder." }, "spamAt": { "type": "string", "description": "ISO 8601 timestamp of when the user marked the resource as spam. Absent means not spam; used as the sort key for the `Spam` folder." }, "resourceCreatedAt": { "type": "string", "description": "Denormalised copy of the underlying resource's own `created` timestamp. Used as the sparse unread-index sort key so the unread feed surfaces oldest resources first, not oldest state rows." }, "flags": { "type": "object", "additionalProperties": true, "description": "Open-ended per-resource flags (e.g. `{muted: true}` on conversations, `{pinned: true}` on candidates). First-class state goes on the top-level attributes; ad-hoc state lives here." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "states_options", "description": "States Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_state", "description": "Show State", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_state", "description": "Update State", "parameters": { "title": "UpdateStateRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateStateRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "states" ] }, "id": { "type": "string" }, "attributes": { "title": "StateAttributesSchema", "type": "object", "properties": { "userId": { "type": "string", "description": "Owner of this state row. Always the authenticated user; never set by the client." }, "resourceType": { "type": "string", "enum": [ "emails", "chats", "candidates", "conversations", "jobs", "talents", "personas", "reports", "tasks" ], "description": "The kind of resource this state describes. Lives in the composite id as `{resourceType}:{resourceId}`." }, "resourceId": { "type": "string", "description": "Id of the resource this state describes (e.g. an emailId, candidateId)." }, "isSeen": { "type": "boolean", "description": "True if the user has opened the resource at least once. Derived from the presence of `seenAt`; clients can write either `isSeen` or `seenAt` on upsert." }, "isStarred": { "type": "boolean", "description": "True if the user has starred/favourited the resource." }, "isSpam": { "type": "boolean", "description": "True if the user marked this resource as spam. Distinct from the email service's `suppressed` status, which is SES-driven on outbound delivery; this is an inbound, per-user action." }, "seenAt": { "type": "string", "description": "ISO 8601 timestamp of the user's most recent open. Absent means never seen." }, "starredAt": { "type": "string", "description": "ISO 8601 timestamp of when the user starred the resource. Absent means not starred; used as the sort key for the `Starred` folder." }, "spamAt": { "type": "string", "description": "ISO 8601 timestamp of when the user marked the resource as spam. Absent means not spam; used as the sort key for the `Spam` folder." }, "resourceCreatedAt": { "type": "string", "description": "Denormalised copy of the underlying resource's own `created` timestamp. Used as the sparse unread-index sort key so the unread feed surfaces oldest resources first, not oldest state rows." }, "flags": { "type": "object", "additionalProperties": true, "description": "Open-ended per-resource flags (e.g. `{muted: true}` on conversations, `{pinned: true}` on candidates). First-class state goes on the top-level attributes; ad-hoc state lives here." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_state", "description": "Delete State", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "state_options", "description": "State Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_aggregates", "description": "List Aggregates", "parameters": { "type": "object", "properties": { "filterResourceType": { "type": "string", "description": "Only return aggregates for this resource type (e.g. emails, chats, calls, comments).", "enum": [ "emails", "chats", "calls", "comments", "candidates", "conversations", "jobs", "talents", "personas", "reports", "tasks" ] }, "filterDimension": { "type": "string", "description": "Only return aggregates for this dimension (e.g. byFolder, byStatus). Triggers the `meta.by{Dimension}` overlay in the response." }, "filterCategory": { "type": "string", "description": "Only return aggregates for this category within the dimension (e.g. received, sent)." }, "filterKind": { "type": "string", "description": "Only return aggregates for this projection kind.", "enum": [ "total", "seen", "unseen" ] }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "aggregates_options", "description": "Aggregates Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_aggregate", "description": "Show Aggregate", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_aggregate", "description": "Update Aggregate (admin)", "parameters": { "title": "UpdateAggregateRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateAggregateRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "aggregates" ] }, "id": { "type": "string" }, "attributes": { "title": "AggregateAttributesSchema", "type": "object", "properties": { "resourceType": { "type": "string", "description": "The resource being counted (e.g. `emails`, `candidates`). Matches the `resourceType` enum used by the state service." }, "dimension": { "type": "string", "description": "The categorisation axis (e.g. `byFolder` for emails, `byStatus` for candidates). Each owning service publishes its own dimensions." }, "category": { "type": "string", "description": "A specific value within the dimension (e.g. `received`, `sent`, `draft` when dimension=byFolder). Lives in the composite id between dimension and kind." }, "kind": { "type": "string", "enum": [ "total", "unseen", "seen" ], "description": "Which projection of the category this row holds. `total` counts every resource; `seen` counts states with isSeen=true; `unseen` is total minus seen." }, "value": { "type": "integer", "description": "Current counter value. Updated via atomic ADD on event consumption; admin PATCH allows manual correction for drift recovery." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "aggregate_options", "description": "Aggregate Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_signals", "description": "List Signals", "parameters": { "type": "object", "properties": { "filterCategory": { "type": "string", "description": "filterCategory parameter", "enum": [ "inbound_email", "inbound_chat", "inbound_call", "inbound_webapp", "outbound_email", "integration", "auth", "data_access" ] }, "filterAction": { "type": "string", "description": "filterAction parameter", "enum": [ "rejected_unknown_principal", "rejected_language", "rejected_intent", "rejected_closed_context", "rejected_rate_limit", "accepted", "delivery_failed", "integration_error", "data_exported" ] }, "filterActorIdentifier": { "type": "string", "description": "filterActorIdentifier parameter" }, "filterSeverity": { "type": "string", "description": "filterSeverity parameter", "enum": [ "info", "warning", "error" ] }, "filterActorType": { "type": "string", "description": "filterActorType parameter", "enum": [ "user", "candidate", "talent", "guest", "system" ] }, "sort": { "type": "string", "description": "sort parameter" }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "signals_options", "description": "Signals Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_signal", "description": "Show Signal", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "signal_options", "description": "Signal Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_claims", "description": "Check Claim Availability", "parameters": { "type": "object", "properties": { "filterType": { "type": "string", "description": "filterType parameter", "enum": [ "shortcode", "email", "phone" ] }, "filterValue": { "type": "string", "description": "The exact name to check (email address, E.164 phone, or shortCode). Normalized to lowercase server-side." } }, "required": [ "filterType", "filterValue" ] } } }, { "type": "function", "function": { "name": "list_labels", "description": "List Labels", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "filterStatus parameter", "enum": [ "active", "archived" ] }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." } } } } }, { "type": "function", "function": { "name": "create_label", "description": "Create Label", "parameters": { "title": "CreateLabelRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateLabelRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "labels" ] }, "attributes": { "title": "LabelAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Display name. Unique within a scope by convention but not enforced." }, "color": { "type": "string", "description": "Hex or CSS-named color the UI uses to render the label pill." }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "tenant", "user" ], "description": "tenant = visible to every user in the tenant; user = visible only to the owner." }, "ownerId": { "type": "string", "description": "Set server-side from the caller. Tenant-scope: tenantId. User-scope: the authenticated user's full userId." }, "resourceTypes": { "type": "array", "items": { "type": "string" }, "description": "Optional UI hint: if set, the frontend only exposes this label in the picker for these resource types (emails, candidates, ...). Not enforced server-side." }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Archived labels stay readable (for historical assignments) but disappear from the default list." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "labels_options", "description": "Labels Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_label", "description": "Show Label", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_label", "description": "Update Label", "parameters": { "title": "UpdateLabelRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateLabelRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "labels" ] }, "id": { "type": "string" }, "attributes": { "title": "LabelAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Display name. Unique within a scope by convention but not enforced." }, "color": { "type": "string", "description": "Hex or CSS-named color the UI uses to render the label pill." }, "description": { "type": "string" }, "scope": { "type": "string", "enum": [ "tenant", "user" ], "description": "tenant = visible to every user in the tenant; user = visible only to the owner." }, "ownerId": { "type": "string", "description": "Set server-side from the caller. Tenant-scope: tenantId. User-scope: the authenticated user's full userId." }, "resourceTypes": { "type": "array", "items": { "type": "string" }, "description": "Optional UI hint: if set, the frontend only exposes this label in the picker for these resource types (emails, candidates, ...). Not enforced server-side." }, "status": { "type": "string", "enum": [ "active", "archived" ], "description": "Archived labels stay readable (for historical assignments) but disappear from the default list." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_label", "description": "Delete Label", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "label_options", "description": "Label Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_meetings", "description": "List Meetings", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns meetings with the current status (active, scheduled, ended, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "scheduled", "ended", "archived" ] }, "filterCandidate": { "type": "string", "description": "Filter meetings (or other resources) by the linked candidate id. Backed by the CandidateIdIndex GSI on meeting; same convention used by other services for candidate reverse-lookup." }, "filterJob": { "type": "string", "description": "Filter meetings by linked job id. Backed by the JobIdIndex GSI." }, "filterHost": { "type": "string", "description": "Filter meetings by the user hosting (human recruiter or boe user). Backed by the HostIdIndex GSI." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "sort": { "type": "string", "description": "Order results by a time field. Leading `-` means descending\n(newest-first). Accepted values:\n `-created` newest-first by creation time (CreatedIndex)\n `created` oldest-first by creation time\n `-modified` most-recently-modified first (ModifiedIndex)\n `modified` least-recently-modified first\nTakes effect only when no equality filter (filterStatus,\nfilterCandidate, filterHost, filterJob, etc.) dictates a\ndifferent index; equality filters win. Compatible with\ndate-range filters (filterCreatedFrom/To, filterModifiedFrom/To)\nwhich already use the same indexes; sort just picks the\ndirection.", "enum": [ "-created", "created", "-modified", "modified" ] }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_meeting", "description": "Create Meeting", "parameters": { "title": "CreateMeetingRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateMeetingRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "meetings" ] }, "attributes": { "title": "MeetingAttributesSchema", "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "scheduledAt": { "type": "string", "format": "date-time" }, "duration": { "type": "integer" }, "defaultLocale": { "type": "string", "pattern": "^(en|fr|ar|pl|it|cs)(-[A-Za-z0-9]{2,8})*$", "description": "Full BCP-47 locale tag (e.g. `en-US`, `pl-PL`, `fr-FR`, `ar-SA`,\n`it-IT`). Set at creation time; controls the UI language of the\npublic lobby + room pages so a Polish recruiter sharing a link\ngets a Polish lobby regardless of the candidate's browser\nlanguage. Immutable after creation.\n\nNOT to be confused with `languageCode`: that field is auto-detected\nfrom the recorded speech and only populated post-meeting (AI\npipeline), whereas `defaultLocale` is human-picked at creation\ntime and drives UI.\n\nValidation: primary subtag must be one of {en, fr, ar, pl, it, cs};\nfull tags are accepted (en-US, pl-PL, ...). Default chain at\ncreation: request body -> tenant settings.language -> 'en-US'." }, "meetingType": { "type": "string", "enum": [ "chime", "recall", "external" ], "description": "Meeting kind. `chime` = in-product Chime SDK session; `recall` = third-party meeting (Zoom/Meet/Teams/Webex) where a recall.ai bot joins to record + transcribe; `external` = third-party meeting tracked on calendar without a bot." }, "provider": { "type": "string", "enum": [ "chime", "zoom", "meet", "teams", "webex", "other" ], "description": "Where the meeting actually runs. Drives URL parsing and bot dispatch capability." }, "purpose": { "type": "string", "enum": [ "interview", "brief", "sales", "1on1", "kickoff", "client_demo", "internal_sync", "training", "other" ], "description": "Host-declared purpose of the meeting. Set at create time\n(FE chip / template picker). Drives Boe's opener tone and\nthe post-meeting review-page filter.\n\nDistinct from `topicsDiscussed` which is AI-inferred\nmulti-value ground truth from the transcript - the two can\ndisagree (intent vs reality).\n\nValues:\n - `interview` - any candidate-facing screening or interview\n - `brief` - recruiter briefing client on a role\n - `sales` - sales / commercial conversation\n - `1on1` - manager <-> report sync\n - `kickoff` - project / engagement kickoff\n - `client_demo` - product demo to external party\n - `internal_sync` - status update / planning / retro\n - `training` - onboarding / knowledge transfer\n - `other` - everything else" }, "joinUrl": { "type": "string", "description": "Third-party meeting URL (Zoom/Meet/Teams/Webex). Null on chime meetings." }, "joinPassword": { "type": "string", "description": "Optional passcode (most often Zoom)." }, "sourceType": { "type": "string", "description": "Originating resource type. `emails` when the invite arrived via email; null for manually created meetings." }, "sourceId": { "type": "string", "description": "ID of the source resource (e.g. emailId)." }, "recall": { "title": "MeetingRecallSchema", "type": "object", "description": "recall.ai bot session metadata. Only populated on meetingType=recall.", "properties": { "botId": { "type": "string", "description": "recall.ai's identifier for the dispatched bot." }, "botStatus": { "type": "string", "enum": [ "idle", "dispatched", "joined", "recording", "ended", "failed" ], "description": "Bot lifecycle. Drives the workflow's wait-for-end step." }, "joinedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" }, "webhookId": { "type": "string", "description": "Identifier returned by recall.ai for the webhook subscription, useful for debugging callback delivery." }, "runContext": { "type": "object", "additionalProperties": true, "description": "Workflow runContext stashed at dispatch time (runId, shardId, workflowId, triggerId, stepIndex, ...). The webhook receiver reads this back when recall.ai posts bot.done so it can emit WORKFLOW_RUN_STEP_COMPLETED to resume the parked run." } } }, "recordingUrl": { "type": "string", "description": "Post-meeting recording URL. Populated by different paths\ndepending on meetingType:\n - `chime`: presigned S3 URL minted on read (in showMeeting)\n once `concatenationStatus=success`. Null until then.\n - `recall`: written by the recall.ai webhook handler with\n the recall.ai-hosted recording URL.\n - `external`: null - no recording captured.\nFE should treat presence-not-null as \"playable\" regardless\nof meetingType." }, "transcript": { "type": "object", "description": "Post-meeting transcript. Multilingual dict like calls: { langCode: text }.", "additionalProperties": { "type": "string" } }, "mediaRegion": { "type": "string" }, "externalMeetingId": { "type": "string" }, "chimeMeetingId": { "type": "string" }, "chimeMeetingData": { "type": "object", "description": "Raw AWS Chime CreateMeeting `Meeting` object - passed verbatim to chime-sdk-js. Includes MeetingFeatures.Audio.EchoReduction when enabled server-side.", "additionalProperties": true }, "candidateId": { "type": "string", "description": "Top-level scalar mirror of relationships.candidate.data.id, used by the CandidateIdIndex GSI for reverse-lookup ('list meetings for this candidate'). Sparse - present only when the relationship is set. Do NOT set this directly on createMeeting / updateMeeting; pass relationships.candidate instead and the server derives the scalar." }, "jobId": { "type": "string", "description": "Top-level scalar mirror of relationships.job.data.id, used by the JobIdIndex GSI ('list meetings for this job'). Derived server-side from relationships.job." }, "hostId": { "type": "string", "description": "Top-level scalar mirror of relationships.host.data.id (always a users id - human recruiter or boe user). Used by the HostIdIndex GSI for the 'my meetings' dashboard. Derived server-side from relationships.host." }, "notetakerEnabled": { "type": "boolean", "default": true, "description": "When true (default), human-hosted meetings auto-dispatch a Boe notetaker bot at meeting start time. Set false on createMeeting to opt out for sensitive sessions. Ignored when the meeting is itself AI-hosted (host.data.id is a boe user); the host bot already takes notes." }, "recordingStatus": { "type": "string", "enum": [ "recording", "success", "failed" ], "description": "Chime SDK Media Capture Pipeline lifecycle. Set by the Boe bot when it starts/stops the capture. Set only for `meetingType=chime`; null on recall/external." }, "mediaCapturePipelineArn": { "type": "string", "description": "Chime SDK Media Capture Pipeline ARN. Internal; FE shouldn't need this directly. Set only for `meetingType=chime`." }, "recordingS3Prefix": { "type": "string", "description": "S3 key prefix where capture pipeline wrote composited-video chunks. Inside the meeting service bucket. Set only for `meetingType=chime`." }, "recordingStartedAt": { "type": "string", "format": "date-time", "description": "Set only for `meetingType=chime`." }, "recordingEndedAt": { "type": "string", "format": "date-time", "description": "Set only for `meetingType=chime`." }, "recordingError": { "type": "string", "description": "Set when `recordingStatus=failed`. Includes the AWS error name + message. Set only for `meetingType=chime`." }, "concatenationStatus": { "type": "string", "enum": [ "running", "success", "failed" ], "description": "Chime SDK Media Concatenation Pipeline lifecycle. Concat merges the ~5s capture chunks into one composited-video.mp4. Flipped to `success` by the ffmpeg-extract Lambda the moment the merged MP4 lands in S3. Set only for `meetingType=chime`." }, "concatenationPipelineArn": { "type": "string", "description": "Concat pipeline ARN. Last path component is the {concatId} used as the merged MP4 filename. Set only for `meetingType=chime`." }, "concatenationS3Prefix": { "type": "string", "description": "S3 key prefix where the concat output lands. Usually {shardId}/{meetingId}/merged/. Set only for `meetingType=chime`." }, "concatenationStartedAt": { "type": "string", "format": "date-time", "description": "Set only for `meetingType=chime`." }, "concatenationEndedAt": { "type": "string", "format": "date-time", "description": "Set only for `meetingType=chime`." }, "concatenationError": { "type": "string", "description": "Set when `concatenationStatus=failed`. Set only for `meetingType=chime`." }, "aiProcessingStatus": { "type": "string", "enum": [ "running", "success", "failed" ], "description": "Phase 3 Step Function (ffmpeg + gpt-audio + translate + finalize) lifecycle. Set by the finalize Lambda." }, "aiProcessingStartedAt": { "type": "string", "format": "date-time" }, "aiProcessingEndedAt": { "type": "string", "format": "date-time" }, "aiProcessingError": { "type": "string" }, "transcriptSegments": { "type": "array", "description": "Time-coded transcript turns. Same shape as call transcriptSegments + adds attendeeId so FE can colour-code participants.", "items": { "title": "MeetingTranscriptSegmentSchema", "type": "object", "description": "Single speaker turn in the meeting transcript. Mirrors CallTranscriptSegmentSchema + attendeeId.", "properties": { "startMs": { "type": "integer", "description": "Offset from start of recording, milliseconds." }, "endMs": { "type": "integer" }, "speakerType": { "type": "string", "enum": [ "ai", "human" ] }, "speakerName": { "type": "string", "description": "Display name resolved from the meeting row (aiAttendees + participants), with a Speaker {id-suffix} fallback for unrecognised attendees." }, "attendeeId": { "type": "string", "description": "chimeAttendeeId so FE can map back to the attendee record (avatar / colour / etc)." }, "text": { "type": "string", "description": "Verbatim spoken text in the source language. NOT translated; use transcript[locale] for translated joined-text views." } } } }, "speakerStats": { "type": "array", "description": "Per-speaker talk percentage in basis points (10000 = 100%).", "items": { "title": "MeetingSpeakerStatSchema", "type": "object", "properties": { "attendeeId": { "type": "string" }, "speakerType": { "type": "string", "enum": [ "ai", "human" ] }, "speakerName": { "type": "string" }, "talkPercentageBp": { "type": "integer", "description": "Talk percentage in basis points (10000 = 100%)." } } } }, "languageCode": { "type": "string", "description": "BCP-47 primary language of the meeting, auto-detected by gpt-audio." }, "summary": { "type": "object", "description": "AI-generated 2-4 paragraph summary per locale. Keyed by\nBCP-47 locale (e.g. `en-US`, `pl-PL`); values are strings.\nThe source language (matches `languageCode`) is always\npresent; tenant target locales are added by the\npost-meeting AI translation step. FE selects the locale to\nrender (no auto-flatten on read). Same shape as `keyNotes`.", "additionalProperties": { "type": "string" } }, "summaryGeneratedAt": { "type": "string", "format": "date-time" }, "keyNotes": { "type": "object", "description": "3-5 prose bullets per locale distilling the meeting's\nsubstance. Keyed by BCP-47 locale (e.g. `en-US`, `pl-PL`);\nvalues are arrays of strings. The source language (matches\n`languageCode`) is always present; tenant target locales are\nadded by the post-meeting AI translation step. FE selects\nthe locale to render (no auto-flatten on read).", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "topicsDiscussed": { "type": "array", "description": "Stable facet keys from the meeting topic dictionary (FE renders human labels via shared dict).", "items": { "type": "string" } }, "sentiment": { "type": "string", "enum": [ "positive", "neutral", "negative", "mixed" ] }, "delivery": { "type": "object", "description": "Vocal delivery cues for the candidate from the audio model (judged\nfrom voice, not the words alone). One Map attribute, NOT localized -\nFE renders each as a label/meter. Only populated for interview-purpose\nmeetings; null otherwise.", "properties": { "confidence": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "How composed/assured the candidate sounded." }, "engagement": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Energy / interest level." }, "clarity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "How clearly/structured the candidate spoke." }, "pace": { "type": "string", "enum": [ "slow", "steady", "fast" ], "description": "Speaking speed." } } }, "status": { "type": "string", "enum": [ "active", "scheduled", "ended", "archived" ] }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "MeetingRelationshipsSchema", "type": "object", "properties": { "files": { "title": "MeetingRelationshipsFilesSchema", "description": "File attachments shared in this meeting (File entities). To-many; container-owns-files.", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "MeetingRelationshipsFilesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "links": { "title": "MeetingRelationshipsLinksSchema", "description": "URLs shared in this meeting, each fetched to markdown (Crawl4AI Link). To-many; container-owns-links.", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "MeetingRelationshipsLinksDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "team": { "title": "MeetingRelationshipsTeamSchema", "type": "object", "description": "Tenant users with stake in this meeting (host + co-hosts + observers + HR backup). Drives access control + 'my meetings' notifications + dashboard visibility. Candidates and guests do NOT live here - they appear in the attendees relationship once they join Chime.", "properties": { "data": { "type": "array", "items": { "title": "MeetingRelationshipsTeamDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "calendar": { "title": "MeetingRelationshipsCalendarSchema", "type": "object", "description": "Calendar this meeting is booked on. Typically boe.calendar for recall meetings, or a shared room calendar for chime.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "conversation": { "title": "MeetingRelationshipsConversationSchema", "type": "object", "description": "Conversation this meeting is threaded into. The post-meeting AI summary lands as a comment on this conversation.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "candidate": { "title": "MeetingRelationshipsCandidateSchema", "type": "object", "description": "Candidate the meeting is about, when known (e.g. interview). Setting this also writes the top-level candidateId scalar (CandidateIdIndex GSI key) so the 'meetings for candidate X' query is a direct GSI hit.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "talent": { "title": "MeetingRelationshipsTalentSchema", "type": "object", "description": "Talent the meeting is about, when known.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "host": { "title": "MeetingRelationshipsHostSchema", "type": "object", "description": "User leading the meeting. May be a human recruiter or a boe user (e.g. usr-boe-interviewer for AI-hosted sessions). Setting this also writes the top-level hostId scalar (HostIdIndex GSI key) so the 'my meetings' dashboard query is a direct GSI hit. Always points at the users resource - there is no separate 'aiHost' shape because Boe IS a user.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "job": { "title": "MeetingRelationshipsJobSchema", "type": "object", "description": "Job opening the meeting is about. Drives interviewer-bot context enrichment (job description, mustHaves, competencies auto-loaded into the prompt) and the 'meetings for this role' job-page view. Setting this also writes the top-level jobId scalar (JobIdIndex GSI key).", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "attendees": { "title": "MeetingRelationshipsAttendeesSchema", "type": "object", "description": "Chime attendee records - everyone with a live or terminated Chime SDK attendee for this meeting (humans + bots, unified). Use `?include=attendees,attendees.user,attendees.candidate` on showMeeting / listMeetings to sideload the full roster in one round-trip. Not embedded in attributes - relationship + sideload only.", "properties": { "data": { "type": "array", "items": { "title": "MeetingRelationshipsAttendeesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string", "description": "Chime attendee id (resource id of the attendee)." } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "meetings_options", "description": "Meetings Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_meeting", "description": "Show Meeting", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_meeting", "description": "Update Meeting", "parameters": { "title": "UpdateMeetingRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateMeetingRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "meetings" ] }, "id": { "type": "string" }, "attributes": { "title": "MeetingAttributesSchema", "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "scheduledAt": { "type": "string", "format": "date-time" }, "duration": { "type": "integer" }, "defaultLocale": { "type": "string", "pattern": "^(en|fr|ar|pl|it|cs)(-[A-Za-z0-9]{2,8})*$", "description": "Full BCP-47 locale tag (e.g. `en-US`, `pl-PL`, `fr-FR`, `ar-SA`,\n`it-IT`). Set at creation time; controls the UI language of the\npublic lobby + room pages so a Polish recruiter sharing a link\ngets a Polish lobby regardless of the candidate's browser\nlanguage. Immutable after creation.\n\nNOT to be confused with `languageCode`: that field is auto-detected\nfrom the recorded speech and only populated post-meeting (AI\npipeline), whereas `defaultLocale` is human-picked at creation\ntime and drives UI.\n\nValidation: primary subtag must be one of {en, fr, ar, pl, it, cs};\nfull tags are accepted (en-US, pl-PL, ...). Default chain at\ncreation: request body -> tenant settings.language -> 'en-US'." }, "meetingType": { "type": "string", "enum": [ "chime", "recall", "external" ], "description": "Meeting kind. `chime` = in-product Chime SDK session; `recall` = third-party meeting (Zoom/Meet/Teams/Webex) where a recall.ai bot joins to record + transcribe; `external` = third-party meeting tracked on calendar without a bot." }, "provider": { "type": "string", "enum": [ "chime", "zoom", "meet", "teams", "webex", "other" ], "description": "Where the meeting actually runs. Drives URL parsing and bot dispatch capability." }, "purpose": { "type": "string", "enum": [ "interview", "brief", "sales", "1on1", "kickoff", "client_demo", "internal_sync", "training", "other" ], "description": "Host-declared purpose of the meeting. Set at create time\n(FE chip / template picker). Drives Boe's opener tone and\nthe post-meeting review-page filter.\n\nDistinct from `topicsDiscussed` which is AI-inferred\nmulti-value ground truth from the transcript - the two can\ndisagree (intent vs reality).\n\nValues:\n - `interview` - any candidate-facing screening or interview\n - `brief` - recruiter briefing client on a role\n - `sales` - sales / commercial conversation\n - `1on1` - manager <-> report sync\n - `kickoff` - project / engagement kickoff\n - `client_demo` - product demo to external party\n - `internal_sync` - status update / planning / retro\n - `training` - onboarding / knowledge transfer\n - `other` - everything else" }, "joinUrl": { "type": "string", "description": "Third-party meeting URL (Zoom/Meet/Teams/Webex). Null on chime meetings." }, "joinPassword": { "type": "string", "description": "Optional passcode (most often Zoom)." }, "sourceType": { "type": "string", "description": "Originating resource type. `emails` when the invite arrived via email; null for manually created meetings." }, "sourceId": { "type": "string", "description": "ID of the source resource (e.g. emailId)." }, "recall": { "title": "MeetingRecallSchema", "type": "object", "description": "recall.ai bot session metadata. Only populated on meetingType=recall.", "properties": { "botId": { "type": "string", "description": "recall.ai's identifier for the dispatched bot." }, "botStatus": { "type": "string", "enum": [ "idle", "dispatched", "joined", "recording", "ended", "failed" ], "description": "Bot lifecycle. Drives the workflow's wait-for-end step." }, "joinedAt": { "type": "string", "format": "date-time" }, "endedAt": { "type": "string", "format": "date-time" }, "webhookId": { "type": "string", "description": "Identifier returned by recall.ai for the webhook subscription, useful for debugging callback delivery." }, "runContext": { "type": "object", "additionalProperties": true, "description": "Workflow runContext stashed at dispatch time (runId, shardId, workflowId, triggerId, stepIndex, ...). The webhook receiver reads this back when recall.ai posts bot.done so it can emit WORKFLOW_RUN_STEP_COMPLETED to resume the parked run." } } }, "recordingUrl": { "type": "string", "description": "Post-meeting recording URL. Populated by different paths\ndepending on meetingType:\n - `chime`: presigned S3 URL minted on read (in showMeeting)\n once `concatenationStatus=success`. Null until then.\n - `recall`: written by the recall.ai webhook handler with\n the recall.ai-hosted recording URL.\n - `external`: null - no recording captured.\nFE should treat presence-not-null as \"playable\" regardless\nof meetingType." }, "transcript": { "type": "object", "description": "Post-meeting transcript. Multilingual dict like calls: { langCode: text }.", "additionalProperties": { "type": "string" } }, "mediaRegion": { "type": "string" }, "externalMeetingId": { "type": "string" }, "chimeMeetingId": { "type": "string" }, "chimeMeetingData": { "type": "object", "description": "Raw AWS Chime CreateMeeting `Meeting` object - passed verbatim to chime-sdk-js. Includes MeetingFeatures.Audio.EchoReduction when enabled server-side.", "additionalProperties": true }, "candidateId": { "type": "string", "description": "Top-level scalar mirror of relationships.candidate.data.id, used by the CandidateIdIndex GSI for reverse-lookup ('list meetings for this candidate'). Sparse - present only when the relationship is set. Do NOT set this directly on createMeeting / updateMeeting; pass relationships.candidate instead and the server derives the scalar." }, "jobId": { "type": "string", "description": "Top-level scalar mirror of relationships.job.data.id, used by the JobIdIndex GSI ('list meetings for this job'). Derived server-side from relationships.job." }, "hostId": { "type": "string", "description": "Top-level scalar mirror of relationships.host.data.id (always a users id - human recruiter or boe user). Used by the HostIdIndex GSI for the 'my meetings' dashboard. Derived server-side from relationships.host." }, "notetakerEnabled": { "type": "boolean", "default": true, "description": "When true (default), human-hosted meetings auto-dispatch a Boe notetaker bot at meeting start time. Set false on createMeeting to opt out for sensitive sessions. Ignored when the meeting is itself AI-hosted (host.data.id is a boe user); the host bot already takes notes." }, "recordingStatus": { "type": "string", "enum": [ "recording", "success", "failed" ], "description": "Chime SDK Media Capture Pipeline lifecycle. Set by the Boe bot when it starts/stops the capture. Set only for `meetingType=chime`; null on recall/external." }, "mediaCapturePipelineArn": { "type": "string", "description": "Chime SDK Media Capture Pipeline ARN. Internal; FE shouldn't need this directly. Set only for `meetingType=chime`." }, "recordingS3Prefix": { "type": "string", "description": "S3 key prefix where capture pipeline wrote composited-video chunks. Inside the meeting service bucket. Set only for `meetingType=chime`." }, "recordingStartedAt": { "type": "string", "format": "date-time", "description": "Set only for `meetingType=chime`." }, "recordingEndedAt": { "type": "string", "format": "date-time", "description": "Set only for `meetingType=chime`." }, "recordingError": { "type": "string", "description": "Set when `recordingStatus=failed`. Includes the AWS error name + message. Set only for `meetingType=chime`." }, "concatenationStatus": { "type": "string", "enum": [ "running", "success", "failed" ], "description": "Chime SDK Media Concatenation Pipeline lifecycle. Concat merges the ~5s capture chunks into one composited-video.mp4. Flipped to `success` by the ffmpeg-extract Lambda the moment the merged MP4 lands in S3. Set only for `meetingType=chime`." }, "concatenationPipelineArn": { "type": "string", "description": "Concat pipeline ARN. Last path component is the {concatId} used as the merged MP4 filename. Set only for `meetingType=chime`." }, "concatenationS3Prefix": { "type": "string", "description": "S3 key prefix where the concat output lands. Usually {shardId}/{meetingId}/merged/. Set only for `meetingType=chime`." }, "concatenationStartedAt": { "type": "string", "format": "date-time", "description": "Set only for `meetingType=chime`." }, "concatenationEndedAt": { "type": "string", "format": "date-time", "description": "Set only for `meetingType=chime`." }, "concatenationError": { "type": "string", "description": "Set when `concatenationStatus=failed`. Set only for `meetingType=chime`." }, "aiProcessingStatus": { "type": "string", "enum": [ "running", "success", "failed" ], "description": "Phase 3 Step Function (ffmpeg + gpt-audio + translate + finalize) lifecycle. Set by the finalize Lambda." }, "aiProcessingStartedAt": { "type": "string", "format": "date-time" }, "aiProcessingEndedAt": { "type": "string", "format": "date-time" }, "aiProcessingError": { "type": "string" }, "transcriptSegments": { "type": "array", "description": "Time-coded transcript turns. Same shape as call transcriptSegments + adds attendeeId so FE can colour-code participants.", "items": { "title": "MeetingTranscriptSegmentSchema", "type": "object", "description": "Single speaker turn in the meeting transcript. Mirrors CallTranscriptSegmentSchema + attendeeId.", "properties": { "startMs": { "type": "integer", "description": "Offset from start of recording, milliseconds." }, "endMs": { "type": "integer" }, "speakerType": { "type": "string", "enum": [ "ai", "human" ] }, "speakerName": { "type": "string", "description": "Display name resolved from the meeting row (aiAttendees + participants), with a Speaker {id-suffix} fallback for unrecognised attendees." }, "attendeeId": { "type": "string", "description": "chimeAttendeeId so FE can map back to the attendee record (avatar / colour / etc)." }, "text": { "type": "string", "description": "Verbatim spoken text in the source language. NOT translated; use transcript[locale] for translated joined-text views." } } } }, "speakerStats": { "type": "array", "description": "Per-speaker talk percentage in basis points (10000 = 100%).", "items": { "title": "MeetingSpeakerStatSchema", "type": "object", "properties": { "attendeeId": { "type": "string" }, "speakerType": { "type": "string", "enum": [ "ai", "human" ] }, "speakerName": { "type": "string" }, "talkPercentageBp": { "type": "integer", "description": "Talk percentage in basis points (10000 = 100%)." } } } }, "languageCode": { "type": "string", "description": "BCP-47 primary language of the meeting, auto-detected by gpt-audio." }, "summary": { "type": "object", "description": "AI-generated 2-4 paragraph summary per locale. Keyed by\nBCP-47 locale (e.g. `en-US`, `pl-PL`); values are strings.\nThe source language (matches `languageCode`) is always\npresent; tenant target locales are added by the\npost-meeting AI translation step. FE selects the locale to\nrender (no auto-flatten on read). Same shape as `keyNotes`.", "additionalProperties": { "type": "string" } }, "summaryGeneratedAt": { "type": "string", "format": "date-time" }, "keyNotes": { "type": "object", "description": "3-5 prose bullets per locale distilling the meeting's\nsubstance. Keyed by BCP-47 locale (e.g. `en-US`, `pl-PL`);\nvalues are arrays of strings. The source language (matches\n`languageCode`) is always present; tenant target locales are\nadded by the post-meeting AI translation step. FE selects\nthe locale to render (no auto-flatten on read).", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "topicsDiscussed": { "type": "array", "description": "Stable facet keys from the meeting topic dictionary (FE renders human labels via shared dict).", "items": { "type": "string" } }, "sentiment": { "type": "string", "enum": [ "positive", "neutral", "negative", "mixed" ] }, "delivery": { "type": "object", "description": "Vocal delivery cues for the candidate from the audio model (judged\nfrom voice, not the words alone). One Map attribute, NOT localized -\nFE renders each as a label/meter. Only populated for interview-purpose\nmeetings; null otherwise.", "properties": { "confidence": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "How composed/assured the candidate sounded." }, "engagement": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Energy / interest level." }, "clarity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "How clearly/structured the candidate spoke." }, "pace": { "type": "string", "enum": [ "slow", "steady", "fast" ], "description": "Speaking speed." } } }, "status": { "type": "string", "enum": [ "active", "scheduled", "ended", "archived" ] }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_meeting", "description": "Delete Meeting", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "meeting_options", "description": "Meeting Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_meeting_attendees", "description": "List Meeting Attendees", "parameters": { "type": "object", "properties": { "include": { "type": "string", "description": "JSON:API compound document request - comma-separated list of relationship paths to include in the response (e.g. `feedbacks`, `feedbacks,boeUser`). Currently advisory: the service always returns all declared relationships with empty defaults." } } } } }, { "type": "function", "function": { "name": "create_meeting_attendee", "description": "Create Meeting Attendee", "parameters": { "title": "CreateMeetingAttendeeRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateMeetingAttendeeRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "attendees" ] }, "attributes": { "title": "MeetingAttendeeAttributesSchema", "type": "object", "description": "Chime attendee record - someone (or some bot) with a live or terminated\nChime SDK attendee for this meeting. Unified across human-auth +\nhuman-guest + AI; principalType + the optional relationships disambiguate.\nUsed both as the createMeetingAttendee request body shape (subset of fields\naccepted - server ignores fields it sets itself) and as the response shape.", "properties": { "chimeAttendeeId": { "type": "string", "description": "Chime SDK attendee id. Server-generated, immutable. Also the resource id of this attendee. Not accepted on the request - server allocates." }, "externalUserId": { "type": "string", "description": "Namespace-prefixed identifier sent to Chime CreateAttendee. Format: `user:` for auth humans, `guest:` for lobby walk-ins, `boe:` for AI users. Visible in Chime State Change events so any consumer can identify the principal type without a DB join. Derived server-side from principalType / user.type - do not set on the request." }, "joinToken": { "type": "string", "description": "One-time Chime SDK join token. Present only on the createMeetingAttendee response; do NOT cache or re-use - request a fresh attendee if the join fails." }, "principalType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Type of the underlying principal who owns this attendance. Mirrors call.fromType / call.toType taxonomy so the same vocabulary spans channels. Required on createMeetingAttendee request." }, "principalId": { "type": "string", "description": "Stable id of the principal (e.g. usr-anna, cnd-tomek, gst-xyz). For namespace `boe:` attendees this is the boe user's id - Boe is a user just like a human, the principalType is still 'user'. Required on createMeetingAttendee request unless principalType=guest (then the server allocates a guest id)." }, "name": { "type": "string", "description": "Display name shown in the roster. Source: user.name for principalType=user (auth or boe), lobby-typed name for guest, candidate/talent name for those types. Accepted on the request as an override; otherwise server resolves it from the principal." }, "role": { "type": "string", "enum": [ "host", "attendee", "candidate", "observer", "interviewer", "notetaker", "sales", "presenter", "other" ], "description": "Function this attendee plays in THIS meeting. Distinct from user.type (which says human-vs-bot at the user level). At most one `host` per meeting. AI bot roles (interviewer / notetaker / sales / presenter) drive prompt template selection in the bot container; `presenter` additionally starts a Chime content share for slide playback." }, "status": { "type": "string", "enum": [ "joining", "active", "left", "dropped", "ended", "error" ], "description": "Lifecycle on the attendee record.\n joining - row created, attendee not yet on Chime grid (typical for bots between dispatch and Chime ack, or for fresh createMeetingAttendee responses pre-join)\n active - present on the Chime grid, audio bridging\n left - left cleanly (clicked leave or natural end)\n dropped - lost connection or network drop (per Chime AttendeeDropped event)\n ended - bot path: server-initiated dismiss (DELETE) or natural completion\n error - bot dispatch / join failed; see errorMessage\nServer-managed - do not set on the request." }, "email": { "type": "string", "description": "Optional. Auth humans: from user profile (server-resolved). Guests: from lobby form (accepted on request)." }, "phone": { "type": "string", "description": "Optional. Typed in lobby form when present (guest only)." }, "voice": { "type": "string", "description": "AI only. gpt-realtime voice used at dispatch: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar. Female-leaning: coral, sage, shimmer. Defaults to a role-based voice when omitted." }, "avatarId": { "type": "string", "description": "AI only. HeyGen LiveAvatar avatar id for Boe's on-grid video, used at dispatch. Overrides the server default avatar; omit to use the default. Persisted on the attendee row and returned on reads (resolution at dispatch: request avatarId -> boe user settings.presence.liveAvatarId -> server default)." }, "voiceGender": { "type": "string", "enum": [ "male", "female" ], "description": "AI only, server-stamped at dispatch when the voice came from the boe user's settings.presence (request-picked voices fall back to the container's voice-derived gender). Returned on reads so FE can mirror the bot's presenting gender." }, "config": { "type": "object", "additionalProperties": true, "description": "AI only. Per-bot runtime config: mode, language, targetLanguage, persona, faceId, context (job-context auto-enrichment seed). Echoed back so FE can confirm what the bot received." }, "taskArn": { "type": "string", "description": "AI only. ECS task ARN for the bot (operational). Server-managed." }, "errorMessage": { "type": "string", "description": "Populated when status=error." }, "joinedAt": { "type": "string", "format": "date-time", "description": "Server-stamped from chime:AttendeeJoined event." }, "leftAt": { "type": "string", "format": "date-time", "description": "Server-stamped from chime:AttendeeLeft / Dropped event." }, "experienceRating": { "type": "object", "description": "Post-meeting subjective rating submitted by the attendee after\nthey left. Each dimension is 1-5 (1=very bad, 5=very good).\nSubmit gate (server-side): only accepted while status is in\n{left, dropped, ended} - 400 otherwise. submittedAt is\nserver-stamped; clients cannot set it. Schema is forward-\ncompatible - new dimensions can be added without migration.", "properties": { "audioVideo": { "type": "integer", "minimum": 1, "maximum": 5, "description": "1=Very bad, 5=Very good. Captures the attendee's perception of audio + video quality during the call." }, "submittedAt": { "type": "string", "format": "date-time", "description": "Server-stamped on PATCH. Client-supplied values are ignored." } } }, "chimeMeetingData": { "type": "object", "additionalProperties": true, "description": "Raw AWS Chime CreateMeeting `Meeting` object - passed verbatim to chime-sdk-js. Only on the createMeetingAttendee response (so the joining client gets everything it needs in one round-trip); not stored on the row." } } } } } } } } }, { "type": "function", "function": { "name": "meeting_attendees_options", "description": "Meeting Attendees Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_guest_meeting_attendees", "description": "List Guest Meeting Attendees", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "create_guest_meeting_attendee", "description": "Create Guest Meeting Attendee", "parameters": { "title": "CreateMeetingAttendeeRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateMeetingAttendeeRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "attendees" ] }, "attributes": { "title": "MeetingAttendeeAttributesSchema", "type": "object", "description": "Chime attendee record - someone (or some bot) with a live or terminated\nChime SDK attendee for this meeting. Unified across human-auth +\nhuman-guest + AI; principalType + the optional relationships disambiguate.\nUsed both as the createMeetingAttendee request body shape (subset of fields\naccepted - server ignores fields it sets itself) and as the response shape.", "properties": { "chimeAttendeeId": { "type": "string", "description": "Chime SDK attendee id. Server-generated, immutable. Also the resource id of this attendee. Not accepted on the request - server allocates." }, "externalUserId": { "type": "string", "description": "Namespace-prefixed identifier sent to Chime CreateAttendee. Format: `user:` for auth humans, `guest:` for lobby walk-ins, `boe:` for AI users. Visible in Chime State Change events so any consumer can identify the principal type without a DB join. Derived server-side from principalType / user.type - do not set on the request." }, "joinToken": { "type": "string", "description": "One-time Chime SDK join token. Present only on the createMeetingAttendee response; do NOT cache or re-use - request a fresh attendee if the join fails." }, "principalType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Type of the underlying principal who owns this attendance. Mirrors call.fromType / call.toType taxonomy so the same vocabulary spans channels. Required on createMeetingAttendee request." }, "principalId": { "type": "string", "description": "Stable id of the principal (e.g. usr-anna, cnd-tomek, gst-xyz). For namespace `boe:` attendees this is the boe user's id - Boe is a user just like a human, the principalType is still 'user'. Required on createMeetingAttendee request unless principalType=guest (then the server allocates a guest id)." }, "name": { "type": "string", "description": "Display name shown in the roster. Source: user.name for principalType=user (auth or boe), lobby-typed name for guest, candidate/talent name for those types. Accepted on the request as an override; otherwise server resolves it from the principal." }, "role": { "type": "string", "enum": [ "host", "attendee", "candidate", "observer", "interviewer", "notetaker", "sales", "presenter", "other" ], "description": "Function this attendee plays in THIS meeting. Distinct from user.type (which says human-vs-bot at the user level). At most one `host` per meeting. AI bot roles (interviewer / notetaker / sales / presenter) drive prompt template selection in the bot container; `presenter` additionally starts a Chime content share for slide playback." }, "status": { "type": "string", "enum": [ "joining", "active", "left", "dropped", "ended", "error" ], "description": "Lifecycle on the attendee record.\n joining - row created, attendee not yet on Chime grid (typical for bots between dispatch and Chime ack, or for fresh createMeetingAttendee responses pre-join)\n active - present on the Chime grid, audio bridging\n left - left cleanly (clicked leave or natural end)\n dropped - lost connection or network drop (per Chime AttendeeDropped event)\n ended - bot path: server-initiated dismiss (DELETE) or natural completion\n error - bot dispatch / join failed; see errorMessage\nServer-managed - do not set on the request." }, "email": { "type": "string", "description": "Optional. Auth humans: from user profile (server-resolved). Guests: from lobby form (accepted on request)." }, "phone": { "type": "string", "description": "Optional. Typed in lobby form when present (guest only)." }, "voice": { "type": "string", "description": "AI only. gpt-realtime voice used at dispatch: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar. Female-leaning: coral, sage, shimmer. Defaults to a role-based voice when omitted." }, "avatarId": { "type": "string", "description": "AI only. HeyGen LiveAvatar avatar id for Boe's on-grid video, used at dispatch. Overrides the server default avatar; omit to use the default. Persisted on the attendee row and returned on reads (resolution at dispatch: request avatarId -> boe user settings.presence.liveAvatarId -> server default)." }, "voiceGender": { "type": "string", "enum": [ "male", "female" ], "description": "AI only, server-stamped at dispatch when the voice came from the boe user's settings.presence (request-picked voices fall back to the container's voice-derived gender). Returned on reads so FE can mirror the bot's presenting gender." }, "config": { "type": "object", "additionalProperties": true, "description": "AI only. Per-bot runtime config: mode, language, targetLanguage, persona, faceId, context (job-context auto-enrichment seed). Echoed back so FE can confirm what the bot received." }, "taskArn": { "type": "string", "description": "AI only. ECS task ARN for the bot (operational). Server-managed." }, "errorMessage": { "type": "string", "description": "Populated when status=error." }, "joinedAt": { "type": "string", "format": "date-time", "description": "Server-stamped from chime:AttendeeJoined event." }, "leftAt": { "type": "string", "format": "date-time", "description": "Server-stamped from chime:AttendeeLeft / Dropped event." }, "experienceRating": { "type": "object", "description": "Post-meeting subjective rating submitted by the attendee after\nthey left. Each dimension is 1-5 (1=very bad, 5=very good).\nSubmit gate (server-side): only accepted while status is in\n{left, dropped, ended} - 400 otherwise. submittedAt is\nserver-stamped; clients cannot set it. Schema is forward-\ncompatible - new dimensions can be added without migration.", "properties": { "audioVideo": { "type": "integer", "minimum": 1, "maximum": 5, "description": "1=Very bad, 5=Very good. Captures the attendee's perception of audio + video quality during the call." }, "submittedAt": { "type": "string", "format": "date-time", "description": "Server-stamped on PATCH. Client-supplied values are ignored." } } }, "chimeMeetingData": { "type": "object", "additionalProperties": true, "description": "Raw AWS Chime CreateMeeting `Meeting` object - passed verbatim to chime-sdk-js. Only on the createMeetingAttendee response (so the joining client gets everything it needs in one round-trip); not stored on the row." } } } } } } } } }, { "type": "function", "function": { "name": "guest_meeting_attendees_options", "description": "Guest Meeting Attendees Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "patch_guest_meeting_attendee", "description": "Patch Guest Meeting Attendee", "parameters": { "title": "CreateMeetingAttendeeRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateMeetingAttendeeRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "attendees" ] }, "attributes": { "title": "MeetingAttendeeAttributesSchema", "type": "object", "description": "Chime attendee record - someone (or some bot) with a live or terminated\nChime SDK attendee for this meeting. Unified across human-auth +\nhuman-guest + AI; principalType + the optional relationships disambiguate.\nUsed both as the createMeetingAttendee request body shape (subset of fields\naccepted - server ignores fields it sets itself) and as the response shape.", "properties": { "chimeAttendeeId": { "type": "string", "description": "Chime SDK attendee id. Server-generated, immutable. Also the resource id of this attendee. Not accepted on the request - server allocates." }, "externalUserId": { "type": "string", "description": "Namespace-prefixed identifier sent to Chime CreateAttendee. Format: `user:` for auth humans, `guest:` for lobby walk-ins, `boe:` for AI users. Visible in Chime State Change events so any consumer can identify the principal type without a DB join. Derived server-side from principalType / user.type - do not set on the request." }, "joinToken": { "type": "string", "description": "One-time Chime SDK join token. Present only on the createMeetingAttendee response; do NOT cache or re-use - request a fresh attendee if the join fails." }, "principalType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Type of the underlying principal who owns this attendance. Mirrors call.fromType / call.toType taxonomy so the same vocabulary spans channels. Required on createMeetingAttendee request." }, "principalId": { "type": "string", "description": "Stable id of the principal (e.g. usr-anna, cnd-tomek, gst-xyz). For namespace `boe:` attendees this is the boe user's id - Boe is a user just like a human, the principalType is still 'user'. Required on createMeetingAttendee request unless principalType=guest (then the server allocates a guest id)." }, "name": { "type": "string", "description": "Display name shown in the roster. Source: user.name for principalType=user (auth or boe), lobby-typed name for guest, candidate/talent name for those types. Accepted on the request as an override; otherwise server resolves it from the principal." }, "role": { "type": "string", "enum": [ "host", "attendee", "candidate", "observer", "interviewer", "notetaker", "sales", "presenter", "other" ], "description": "Function this attendee plays in THIS meeting. Distinct from user.type (which says human-vs-bot at the user level). At most one `host` per meeting. AI bot roles (interviewer / notetaker / sales / presenter) drive prompt template selection in the bot container; `presenter` additionally starts a Chime content share for slide playback." }, "status": { "type": "string", "enum": [ "joining", "active", "left", "dropped", "ended", "error" ], "description": "Lifecycle on the attendee record.\n joining - row created, attendee not yet on Chime grid (typical for bots between dispatch and Chime ack, or for fresh createMeetingAttendee responses pre-join)\n active - present on the Chime grid, audio bridging\n left - left cleanly (clicked leave or natural end)\n dropped - lost connection or network drop (per Chime AttendeeDropped event)\n ended - bot path: server-initiated dismiss (DELETE) or natural completion\n error - bot dispatch / join failed; see errorMessage\nServer-managed - do not set on the request." }, "email": { "type": "string", "description": "Optional. Auth humans: from user profile (server-resolved). Guests: from lobby form (accepted on request)." }, "phone": { "type": "string", "description": "Optional. Typed in lobby form when present (guest only)." }, "voice": { "type": "string", "description": "AI only. gpt-realtime voice used at dispatch: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar. Female-leaning: coral, sage, shimmer. Defaults to a role-based voice when omitted." }, "avatarId": { "type": "string", "description": "AI only. HeyGen LiveAvatar avatar id for Boe's on-grid video, used at dispatch. Overrides the server default avatar; omit to use the default. Persisted on the attendee row and returned on reads (resolution at dispatch: request avatarId -> boe user settings.presence.liveAvatarId -> server default)." }, "voiceGender": { "type": "string", "enum": [ "male", "female" ], "description": "AI only, server-stamped at dispatch when the voice came from the boe user's settings.presence (request-picked voices fall back to the container's voice-derived gender). Returned on reads so FE can mirror the bot's presenting gender." }, "config": { "type": "object", "additionalProperties": true, "description": "AI only. Per-bot runtime config: mode, language, targetLanguage, persona, faceId, context (job-context auto-enrichment seed). Echoed back so FE can confirm what the bot received." }, "taskArn": { "type": "string", "description": "AI only. ECS task ARN for the bot (operational). Server-managed." }, "errorMessage": { "type": "string", "description": "Populated when status=error." }, "joinedAt": { "type": "string", "format": "date-time", "description": "Server-stamped from chime:AttendeeJoined event." }, "leftAt": { "type": "string", "format": "date-time", "description": "Server-stamped from chime:AttendeeLeft / Dropped event." }, "experienceRating": { "type": "object", "description": "Post-meeting subjective rating submitted by the attendee after\nthey left. Each dimension is 1-5 (1=very bad, 5=very good).\nSubmit gate (server-side): only accepted while status is in\n{left, dropped, ended} - 400 otherwise. submittedAt is\nserver-stamped; clients cannot set it. Schema is forward-\ncompatible - new dimensions can be added without migration.", "properties": { "audioVideo": { "type": "integer", "minimum": 1, "maximum": 5, "description": "1=Very bad, 5=Very good. Captures the attendee's perception of audio + video quality during the call." }, "submittedAt": { "type": "string", "format": "date-time", "description": "Server-stamped on PATCH. Client-supplied values are ignored." } } }, "chimeMeetingData": { "type": "object", "additionalProperties": true, "description": "Raw AWS Chime CreateMeeting `Meeting` object - passed verbatim to chime-sdk-js. Only on the createMeetingAttendee response (so the joining client gets everything it needs in one round-trip); not stored on the row." } } } } } } } } }, { "type": "function", "function": { "name": "guest_meeting_attendee_options", "description": "Guest Meeting Attendee Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "meeting_transcription", "description": "Manage Meeting Transcription", "parameters": { "type": "object", "properties": { "action": { "type": "string", "description": "Transcription action: start or stop", "enum": [ "start", "stop" ] }, "requestBody": { "title": "MeetingTranscriptionRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "MeetingTranscriptionRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "transcriptions" ] }, "attributes": { "title": "MeetingTranscriptionSettingsSchema", "type": "object", "properties": { "languageCode": { "type": "string", "description": "Transcribe language code (e.g. en-US, de-DE, es-US)", "default": "en-US" }, "region": { "type": "string", "description": "AWS region for Amazon Transcribe", "default": "us-east-1" }, "contentIdentificationType": { "type": "string", "description": "PII content identification type", "enum": [ "PII" ] } } } } } } } }, "required": [ "action", "requestBody" ] } } }, { "type": "function", "function": { "name": "meeting_transcription_options", "description": "Meeting Transcription Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "create_meeting_ai_session", "description": "Create Meeting AI Session", "parameters": { "title": "CreateMeetingAiSessionRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateMeetingAiSessionRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "ai-sessions" ] }, "attributes": { "title": "MeetingAiSessionSettingsSchema", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "assistant", "assistant-openai", "transcription", "translator-openai" ], "default": "assistant", "description": "Picks the provider + session.type baked into the ephemeral\ntoken.\n'assistant' = Azure eu00, sm-gpt-realtime-2.1,\n session.type=realtime (browser-side Boe).\n'assistant-openai' = OpenAI direct, gpt-realtime-2.1,\n session.type=realtime. Redundant with 'assistant' now that\n Azure eu00 hosts realtime-2 too; kept as a one-release\n safety valve while the Azure preview deployment soaks.\n'transcription' = Azure eu01, sm-gpt-realtime-whisper,\n session.type=transcription (live captions, audio-in /\n text-out only).\n'translator-openai' = OpenAI direct, gpt-realtime-translate,\n session.type=translation (audio-in, translated audio +\n source-language transcript fanned out on data channel).\n Requires targetLanguage." }, "language": { "type": "string", "description": "Reply language for Boe's assistant behaviour (e.g. English). Only applies when mode=assistant." }, "targetLanguage": { "type": "string", "description": "BCP-47 code for the language the translator should produce (e.g. 'pl', 'es', 'en'). Required when mode=translator-openai; ignored otherwise. Defaults to 'en' if omitted." } } } } } } } } }, { "type": "function", "function": { "name": "meeting_ai_session_options", "description": "Meeting AI Session Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_meeting_attendee", "description": "Show Meeting Attendee", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "patch_meeting_attendee", "description": "Patch Meeting Attendee", "parameters": { "title": "CreateMeetingAttendeeRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateMeetingAttendeeRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "attendees" ] }, "attributes": { "title": "MeetingAttendeeAttributesSchema", "type": "object", "description": "Chime attendee record - someone (or some bot) with a live or terminated\nChime SDK attendee for this meeting. Unified across human-auth +\nhuman-guest + AI; principalType + the optional relationships disambiguate.\nUsed both as the createMeetingAttendee request body shape (subset of fields\naccepted - server ignores fields it sets itself) and as the response shape.", "properties": { "chimeAttendeeId": { "type": "string", "description": "Chime SDK attendee id. Server-generated, immutable. Also the resource id of this attendee. Not accepted on the request - server allocates." }, "externalUserId": { "type": "string", "description": "Namespace-prefixed identifier sent to Chime CreateAttendee. Format: `user:` for auth humans, `guest:` for lobby walk-ins, `boe:` for AI users. Visible in Chime State Change events so any consumer can identify the principal type without a DB join. Derived server-side from principalType / user.type - do not set on the request." }, "joinToken": { "type": "string", "description": "One-time Chime SDK join token. Present only on the createMeetingAttendee response; do NOT cache or re-use - request a fresh attendee if the join fails." }, "principalType": { "type": "string", "enum": [ "user", "candidate", "talent", "guest" ], "description": "Type of the underlying principal who owns this attendance. Mirrors call.fromType / call.toType taxonomy so the same vocabulary spans channels. Required on createMeetingAttendee request." }, "principalId": { "type": "string", "description": "Stable id of the principal (e.g. usr-anna, cnd-tomek, gst-xyz). For namespace `boe:` attendees this is the boe user's id - Boe is a user just like a human, the principalType is still 'user'. Required on createMeetingAttendee request unless principalType=guest (then the server allocates a guest id)." }, "name": { "type": "string", "description": "Display name shown in the roster. Source: user.name for principalType=user (auth or boe), lobby-typed name for guest, candidate/talent name for those types. Accepted on the request as an override; otherwise server resolves it from the principal." }, "role": { "type": "string", "enum": [ "host", "attendee", "candidate", "observer", "interviewer", "notetaker", "sales", "presenter", "other" ], "description": "Function this attendee plays in THIS meeting. Distinct from user.type (which says human-vs-bot at the user level). At most one `host` per meeting. AI bot roles (interviewer / notetaker / sales / presenter) drive prompt template selection in the bot container; `presenter` additionally starts a Chime content share for slide playback." }, "status": { "type": "string", "enum": [ "joining", "active", "left", "dropped", "ended", "error" ], "description": "Lifecycle on the attendee record.\n joining - row created, attendee not yet on Chime grid (typical for bots between dispatch and Chime ack, or for fresh createMeetingAttendee responses pre-join)\n active - present on the Chime grid, audio bridging\n left - left cleanly (clicked leave or natural end)\n dropped - lost connection or network drop (per Chime AttendeeDropped event)\n ended - bot path: server-initiated dismiss (DELETE) or natural completion\n error - bot dispatch / join failed; see errorMessage\nServer-managed - do not set on the request." }, "email": { "type": "string", "description": "Optional. Auth humans: from user profile (server-resolved). Guests: from lobby form (accepted on request)." }, "phone": { "type": "string", "description": "Optional. Typed in lobby form when present (guest only)." }, "voice": { "type": "string", "description": "AI only. gpt-realtime voice used at dispatch: alloy, ash, ballad, coral, echo, sage, shimmer, verse, marin, cedar. Female-leaning: coral, sage, shimmer. Defaults to a role-based voice when omitted." }, "avatarId": { "type": "string", "description": "AI only. HeyGen LiveAvatar avatar id for Boe's on-grid video, used at dispatch. Overrides the server default avatar; omit to use the default. Persisted on the attendee row and returned on reads (resolution at dispatch: request avatarId -> boe user settings.presence.liveAvatarId -> server default)." }, "voiceGender": { "type": "string", "enum": [ "male", "female" ], "description": "AI only, server-stamped at dispatch when the voice came from the boe user's settings.presence (request-picked voices fall back to the container's voice-derived gender). Returned on reads so FE can mirror the bot's presenting gender." }, "config": { "type": "object", "additionalProperties": true, "description": "AI only. Per-bot runtime config: mode, language, targetLanguage, persona, faceId, context (job-context auto-enrichment seed). Echoed back so FE can confirm what the bot received." }, "taskArn": { "type": "string", "description": "AI only. ECS task ARN for the bot (operational). Server-managed." }, "errorMessage": { "type": "string", "description": "Populated when status=error." }, "joinedAt": { "type": "string", "format": "date-time", "description": "Server-stamped from chime:AttendeeJoined event." }, "leftAt": { "type": "string", "format": "date-time", "description": "Server-stamped from chime:AttendeeLeft / Dropped event." }, "experienceRating": { "type": "object", "description": "Post-meeting subjective rating submitted by the attendee after\nthey left. Each dimension is 1-5 (1=very bad, 5=very good).\nSubmit gate (server-side): only accepted while status is in\n{left, dropped, ended} - 400 otherwise. submittedAt is\nserver-stamped; clients cannot set it. Schema is forward-\ncompatible - new dimensions can be added without migration.", "properties": { "audioVideo": { "type": "integer", "minimum": 1, "maximum": 5, "description": "1=Very bad, 5=Very good. Captures the attendee's perception of audio + video quality during the call." }, "submittedAt": { "type": "string", "format": "date-time", "description": "Server-stamped on PATCH. Client-supplied values are ignored." } } }, "chimeMeetingData": { "type": "object", "additionalProperties": true, "description": "Raw AWS Chime CreateMeeting `Meeting` object - passed verbatim to chime-sdk-js. Only on the createMeetingAttendee response (so the joining client gets everything it needs in one round-trip); not stored on the row." } } } } } } } } }, { "type": "function", "function": { "name": "delete_meeting_attendee", "description": "Remove Meeting Attendee", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "meeting_attendee_options", "description": "Meeting Attendee Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_meeting_lobby", "description": "Show Meeting Lobby", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "meeting_lobby_options", "description": "Meeting Lobby Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_conversations", "description": "List Conversations", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns conversations with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterTalentId": { "type": "string", "description": "Returns the conversations owned by a talent (the comms hub - all the talent's\nconversations across jobs/candidates, for the talent-details Communication tab).\nServed by the conversation TalentIndex GSI." }, "filterCandidateId": { "type": "string", "description": "Returns the conversations for a single candidate (the per-job view of comms - one\nrecruitment context). Served by the conversation CandidateIndex GSI." }, "filterJobId": { "type": "string", "description": "Returns all conversations for a single job (the role-wide view of comms across\nevery candidate/talent on that job). Served by the conversation JobIndex GSI." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_conversation", "description": "Create Conversation", "parameters": { "title": "CreateConversationRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateConversationRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "conversations" ] }, "attributes": { "title": "ConversationAttributesSchema", "type": "object", "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ], "description": "Conversation name. Can be a plain string or a multilingual object keyed by language code" }, "type": { "type": "string", "description": "Conversation type (e.g., candidates, jobs, talents, personas)" }, "status": { "type": "string" }, "summary": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Multilingual summary keyed by language code" }, "source": { "type": "string", "description": "Source of the conversation" }, "languageCode": { "type": "string", "description": "Preferred language code (e.g., en-US, pl-PL)" }, "isConversationEnd": { "type": "boolean", "description": "Whether the conversation has ended" }, "settings": { "type": "object", "additionalProperties": true, "description": "Conversation settings inherited from job" }, "ttl": { "type": "string", "description": "Time-to-live expiration timestamp" }, "meta": { "type": "object", "additionalProperties": true }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "ConversationRelationshipsSchema", "type": "object", "properties": { "candidate": { "title": "ConversationRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "title": "ConversationRelationshipsCandidateDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "emails": { "title": "ConversationRelationshipsEmailsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "ConversationRelationshipsEmailsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "chats": { "title": "ConversationRelationshipsChatsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "ConversationRelationshipsChatsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "calls": { "title": "ConversationRelationshipsCallsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "ConversationRelationshipsCallsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "meetings": { "title": "ConversationRelationshipsMeetingsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "ConversationRelationshipsMeetingsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "talent": { "title": "ConversationRelationshipsTalentSchema", "type": "object", "properties": { "data": { "title": "ConversationRelationshipsTalentDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "job": { "title": "ConversationRelationshipsJobSchema", "type": "object", "properties": { "data": { "title": "ConversationRelationshipsJobDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "conversations_options", "description": "Conversations Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_conversation", "description": "Show Conversation", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_conversation", "description": "Update Conversation", "parameters": { "title": "UpdateConversationRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateConversationRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "conversations" ] }, "id": { "type": "string" }, "attributes": { "title": "ConversationAttributesSchema", "type": "object", "properties": { "name": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ], "description": "Conversation name. Can be a plain string or a multilingual object keyed by language code" }, "type": { "type": "string", "description": "Conversation type (e.g., candidates, jobs, talents, personas)" }, "status": { "type": "string" }, "summary": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Multilingual summary keyed by language code" }, "source": { "type": "string", "description": "Source of the conversation" }, "languageCode": { "type": "string", "description": "Preferred language code (e.g., en-US, pl-PL)" }, "isConversationEnd": { "type": "boolean", "description": "Whether the conversation has ended" }, "settings": { "type": "object", "additionalProperties": true, "description": "Conversation settings inherited from job" }, "ttl": { "type": "string", "description": "Time-to-live expiration timestamp" }, "meta": { "type": "object", "additionalProperties": true }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_conversation", "description": "Delete Conversation", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "conversation_options", "description": "Conversation Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_reports", "description": "List Reports", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns reports with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_report", "description": "Create Report", "parameters": { "title": "CreateReportRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateReportRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "reports" ] }, "attributes": { "title": "ReportAttributesSchema", "type": "object", "required": [ "resourceId", "resourceType" ], "properties": { "resourceId": { "type": "string", "description": "Identifier of the resource this report is associated with (job ID or tenant ID)" }, "resourceType": { "type": "string", "description": "Type of the resource (tenants or jobs)", "enum": [ "tenants", "jobs" ] }, "period": { "type": "string", "description": "Report period frequency", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY" ] }, "reportContent": { "type": "string", "description": "Merged analytics and AI analysis content" }, "settings": { "type": "string", "description": "Report configuration including email recipients and period preferences" }, "shortCode": { "type": "string", "description": "Optional short identifier for the report" }, "source": { "type": "string", "description": "Source of the report creation (e.g. scheduled, manual)" }, "status": { "type": "string", "description": "Current status of the report", "enum": [ "active", "inactive", "pending", "archived", "failed" ] }, "ttl": { "type": "string", "description": "Time-to-live value for automatic report expiration" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "ReportWriteRelationshipsSchema", "type": "object", "description": "WRITE shape for request bodies: the storage-convention plural keys the services and the existing SDK writer classes use. Responses use the wire-shaped RelationshipsSchema instead - the two deliberately differ (PLAN_RELATIONSHIP_CONTRACT.md).", "properties": { "tenants": { "title": "ReportRelationshipsTenantsSchema", "type": "object", "properties": { "data": { "title": "ReportRelationshipsTenantsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "reports_options", "description": "Reports Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_report", "description": "Show Report", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_report", "description": "Update Report", "parameters": { "title": "UpdateReportRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateReportRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "reports" ] }, "id": { "type": "string" }, "attributes": { "title": "ReportAttributesSchema", "type": "object", "required": [ "resourceId", "resourceType" ], "properties": { "resourceId": { "type": "string", "description": "Identifier of the resource this report is associated with (job ID or tenant ID)" }, "resourceType": { "type": "string", "description": "Type of the resource (tenants or jobs)", "enum": [ "tenants", "jobs" ] }, "period": { "type": "string", "description": "Report period frequency", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY" ] }, "reportContent": { "type": "string", "description": "Merged analytics and AI analysis content" }, "settings": { "type": "string", "description": "Report configuration including email recipients and period preferences" }, "shortCode": { "type": "string", "description": "Optional short identifier for the report" }, "source": { "type": "string", "description": "Source of the report creation (e.g. scheduled, manual)" }, "status": { "type": "string", "description": "Current status of the report", "enum": [ "active", "inactive", "pending", "archived", "failed" ] }, "ttl": { "type": "string", "description": "Time-to-live value for automatic report expiration" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_report", "description": "Delete Report", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "report_options", "description": "Report Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_ads", "description": "List Ads", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns ads with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterJobId": { "type": "string", "description": "Returns the ads generated for the given job (JobIndex lookup)." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_ad", "description": "Create Ad", "parameters": { "title": "CreateAdRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateAdRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "ads" ] }, "attributes": { "title": "AdAttributesSchema", "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "pending", "draft", "accepted", "archived", "failed" ], "description": "Lifecycle of the ad. Clients do NOT drive `accepted`: the gate-2\nworkflow's job:accept-artifacts step flips draft -> accepted when the\noperator activates the job. A build-phase ad lands `draft`, a legacy\ncreate-on-activate ad lands `active`, and `failed` is stamped by the\npipeline's own failure handler." }, "platforms": { "type": "object", "description": "Platform-specific ad copy keyed by platform name and language code." }, "files": { "type": "array", "description": "Generated ad artifacts: master images per aspect variant, platform\ncrops, and a zip. Stored in the PRIVATE ad bucket; each entry carries\na short-lived presigned `url` the govern UI renders during review.\n\nThe PUBLIC CDN copy of the apply hero and listing card is written by\nthe `apply:publish` workflow action, which runs automatically as a\nstep of the gate-2 workflow (Activate Job From Operator). There is no\n`ad:publish` action and no status a client can write to trigger\npublication. The published URLs are `heroUrl` / `cardUrl` inside\n`tenants/{tenantShortCode}/apply/{jobShortCode}.json` on the CDN, and\nthey are content-addressed (a regenerated creative gets a new path)\nso they can be cached immutably.\n\nReplaces the never-emitted legacy `images` field.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "master", "image", "zip" ], "description": "master = full aspect render, image = platform crop, zip = bundle." }, "variant": { "type": "string", "enum": [ "square", "landscape" ], "description": "Aspect variant for a master. `portrait` was removed - nothing consumed it." }, "platform": { "type": "string", "description": "Target platform for a crop (linkedin_short / indeed / apply / apply_card / ...)." }, "language": { "type": "string", "pattern": "^[a-z]{2}-[A-Z]{2}$", "description": "Locale of the text composited onto this crop. Present only on\n`type: image`; masters are text-free artwork and the zip is a\nbundle, so both omit it. Absent on crops generated before\nper-locale banners shipped - treat as the job's languageCode." }, "s3Key": { "type": "string" }, "size": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "version": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string", "description": "Short-lived presigned GET url for the preview. Absent if signing failed." } } } }, "settings": { "type": "object" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "AdRelationshipsSchema", "type": "object", "properties": { "job": { "title": "AdRelationshipsJobSchema", "type": "object", "properties": { "data": { "title": "AdRelationshipsJobDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "ads_options", "description": "Ads Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_ad", "description": "Show Ad", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_ad", "description": "Update Ad", "parameters": { "title": "UpdateAdRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateAdRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "ads" ] }, "id": { "type": "string" }, "attributes": { "title": "AdAttributesSchema", "type": "object", "properties": { "jobId": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive", "pending", "draft", "accepted", "archived", "failed" ], "description": "Lifecycle of the ad. Clients do NOT drive `accepted`: the gate-2\nworkflow's job:accept-artifacts step flips draft -> accepted when the\noperator activates the job. A build-phase ad lands `draft`, a legacy\ncreate-on-activate ad lands `active`, and `failed` is stamped by the\npipeline's own failure handler." }, "platforms": { "type": "object", "description": "Platform-specific ad copy keyed by platform name and language code." }, "files": { "type": "array", "description": "Generated ad artifacts: master images per aspect variant, platform\ncrops, and a zip. Stored in the PRIVATE ad bucket; each entry carries\na short-lived presigned `url` the govern UI renders during review.\n\nThe PUBLIC CDN copy of the apply hero and listing card is written by\nthe `apply:publish` workflow action, which runs automatically as a\nstep of the gate-2 workflow (Activate Job From Operator). There is no\n`ad:publish` action and no status a client can write to trigger\npublication. The published URLs are `heroUrl` / `cardUrl` inside\n`tenants/{tenantShortCode}/apply/{jobShortCode}.json` on the CDN, and\nthey are content-addressed (a regenerated creative gets a new path)\nso they can be cached immutably.\n\nReplaces the never-emitted legacy `images` field.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "master", "image", "zip" ], "description": "master = full aspect render, image = platform crop, zip = bundle." }, "variant": { "type": "string", "enum": [ "square", "landscape" ], "description": "Aspect variant for a master. `portrait` was removed - nothing consumed it." }, "platform": { "type": "string", "description": "Target platform for a crop (linkedin_short / indeed / apply / apply_card / ...)." }, "language": { "type": "string", "pattern": "^[a-z]{2}-[A-Z]{2}$", "description": "Locale of the text composited onto this crop. Present only on\n`type: image`; masters are text-free artwork and the zip is a\nbundle, so both omit it. Absent on crops generated before\nper-locale banners shipped - treat as the job's languageCode." }, "s3Key": { "type": "string" }, "size": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "version": { "type": "integer" }, "name": { "type": "string" }, "url": { "type": "string", "description": "Short-lived presigned GET url for the preview. Absent if signing failed." } } } }, "settings": { "type": "object" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_ad", "description": "Delete Ad", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "ad_options", "description": "Ad Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_operations", "description": "List Operations", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns operations with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_operation", "description": "Create Operation", "parameters": { "title": "CreateOperationRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateOperationRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "operations" ] }, "attributes": { "title": "OperationAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Required on create. Human-readable operation name." }, "event": { "type": "string", "description": "Required on create. Colon-notation ATS event code (e.g. rcrt:event:candidate:created); the prefix derives source." }, "eventDetails": { "type": "string", "description": "Required on create. JSON STRING (max 4096) carrying the per-event payload, e.g. {\"talent\":{\"shortCode\":\"123\"},\"job\":{\"shortCode\":\"456\"}}. Parsed to an object in the service:operation:created event copy." }, "source": { "type": "string", "description": "Derived server-side from the event prefix (erecruiter, lever, teamtailor). Read-only." }, "status": { "type": "string", "enum": [ "active", "inactive", "pending", "hold", "archived", "failed" ] }, "parentOperationId": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "OperationRelationshipsSchema", "type": "object", "properties": { "job": { "title": "OperationRelationshipsJobSchema", "type": "object", "properties": { "data": { "title": "OperationRelationshipsJobDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "candidate": { "title": "OperationRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "title": "OperationRelationshipsCandidateDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "operations_options", "description": "Operations Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_operation", "description": "Show Operation", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_operation", "description": "Update Operation", "parameters": { "title": "UpdateOperationRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateOperationRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "operations" ] }, "id": { "type": "string" }, "attributes": { "title": "OperationAttributesSchema", "type": "object", "properties": { "name": { "type": "string", "description": "Required on create. Human-readable operation name." }, "event": { "type": "string", "description": "Required on create. Colon-notation ATS event code (e.g. rcrt:event:candidate:created); the prefix derives source." }, "eventDetails": { "type": "string", "description": "Required on create. JSON STRING (max 4096) carrying the per-event payload, e.g. {\"talent\":{\"shortCode\":\"123\"},\"job\":{\"shortCode\":\"456\"}}. Parsed to an object in the service:operation:created event copy." }, "source": { "type": "string", "description": "Derived server-side from the event prefix (erecruiter, lever, teamtailor). Read-only." }, "status": { "type": "string", "enum": [ "active", "inactive", "pending", "hold", "archived", "failed" ] }, "parentOperationId": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_operation", "description": "Delete Operation", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "operation_options", "description": "Operation Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "teamtailor_webhook", "description": "Teamtailor Company Webhook", "parameters": { "type": "object", "properties": { "payload": { "type": "object", "properties": { "event_name": { "type": "string", "description": "Teamtailor event, e.g. job_application.create." }, "data": { "type": "object" } } }, "signature": { "type": "string", "description": "Legacy v1 payload signature; verification uses the TT-Signature header (v2)." } } } } }, { "type": "function", "function": { "name": "teamtailor_webhook_options", "description": "Teamtailor webhook CORS preflight", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_assessments", "description": "List Assessments", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Filter by template status.", "enum": [ "draft", "active", "archived", "failed", "pending" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_assessment", "description": "Create Assessment", "parameters": { "title": "CreateAssessmentRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateAssessmentRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "assessments" ] }, "attributes": { "title": "AssessmentAttributesSchema", "description": "Template-only attributes for an assessment. The candidate's run of an\nassessment (answers, scores, evaluation, proctoring) lives on the\nAttempt resource - see AttemptAttributesSchema.", "type": "object", "properties": { "status": { "type": "string", "description": "Template lifecycle. Candidate-side state (inProgress/submitted/\nevaluated/etc.) lives on attempts. `pending` is a transient state\nset when the AI Generate Step Function is in flight - the row\nflips to `active` once questions land. `accepted` = the ReCop\napproved this assessment at the operator gate (Create Job From\nBrief, gate 2); set by the job:accept-artifacts workflow action.", "enum": [ "draft", "active", "accepted", "archived", "failed", "pending" ] }, "duration": { "type": "integer", "description": "Time limit for the candidate to complete the assessment, in minutes. Defaults to 30." }, "antiCheatingLevel": { "type": "string", "enum": [ "TOLERANT", "MODERATE", "RIGOROUS" ] }, "passingScore": { "type": "number", "description": "Score threshold (0-100) for `evaluation.passed=true` on attempts of this template. Defaults to 60." }, "languageCode": { "type": "string", "description": "Default language tag used when the candidate UI doesn't specify one (e.g. 'en-US', 'pl-PL')." }, "name": { "type": "object", "description": "Multilingual template name. Keys are locale tags, values are the localized title.", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "description": "Multilingual template description shown to the candidate before they start.", "additionalProperties": { "type": "string" } }, "questions": { "type": "array", "description": "Question bank. See QuestionSchema for per-type schemas.", "items": { "title": "QuestionSchema", "description": "A single assessment question. Eight question types - the optional\nfields below are interpreted based on `type`. See\n`Question.value` shapes in AnswerSchema for what the candidate\nsends back per type.\n\nSECURITY: `answerKey`, `scoringRubric`, and `options[].isCorrect`\nare stripped server-side before responses are returned to candidates\nvia /v1/guest/attempts/* - they are recruiter-only fields.", "type": "object", "required": [ "questionId", "type" ], "properties": { "questionId": { "type": "string", "description": "Stable identifier (e.g. 'q1'). Candidates' answers reference this." }, "type": { "type": "string", "enum": [ "single-choice", "multiple-choice", "scale", "open-text", "ranking", "situational-judgment", "file-upload", "video-recording" ] }, "category": { "type": "string", "description": "Free-form tag for analytics (e.g. 'soft-skills', 'hard-skills', 'general')." }, "difficulty": { "type": "string", "enum": [ "easy", "medium", "hard" ] }, "points": { "type": "number", "description": "Maximum score for this question. Defaults to 1." }, "required": { "type": "boolean" }, "text": { "type": "object", "description": "Multilingual question text.", "additionalProperties": { "type": "string" } }, "options": { "type": "array", "description": "Choices for single-choice / multiple-choice / ranking /\nsituational-judgment. Canonical shape is\n`{ id, text: { locale: string }, isCorrect?: bool }`. Bare\nlocale-map options exist in legacy data but are deprecated.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable option id - candidates' answers reference this." }, "text": { "type": "object", "additionalProperties": { "type": "string" } }, "isCorrect": { "type": "boolean", "description": "Recruiter-only. Stripped server-side from guest responses." } } } }, "scaleMin": { "type": "integer", "description": "Lower bound for `scale` type questions." }, "scaleMax": { "type": "integer", "description": "Upper bound for `scale` type questions." }, "scaleLabels": { "type": "object", "description": "Optional labels per step value, multilingual.\n`{ \"1\": { \"en-US\": \"Strongly disagree\" }, \"5\": { \"en-US\": \"Strongly agree\" } }`.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string" } } }, "placeholder": { "type": "object", "description": "Multilingual placeholder text for `open-text` questions.", "additionalProperties": { "type": "string" } }, "scenario": { "type": "object", "description": "Multilingual scenario body for `situational-judgment` questions.", "additionalProperties": { "type": "string" } }, "acceptedFormats": { "type": "array", "description": "Accepted MIME or extension list for `file-upload` (e.g. ['.pdf', '.png']).", "items": { "type": "string" } }, "maxDuration": { "type": "integer", "description": "Maximum recording length in seconds for `video-recording`." }, "maxAttempts": { "type": "integer", "description": "Maximum recording retakes the candidate may use on `video-recording`." }, "explanation": { "type": "object", "description": "Multilingual explanation shown post-submission on review screens.", "additionalProperties": { "type": "string" } }, "answerKey": { "description": "Recruiter-only. Shape depends on questionType:\n single-choice -> string (option id)\n multiple-choice -> string[] (option ids)\n ranking -> string[] (option ids in order)\n situational-judgment -> { best: string, worst: string }\n scale / open-text -> not used (use scoringRubric)\nType intentionally left unconstrained (Any) - the variant\nshapes resist a oneOf wrapper because pydantic's outer\nDict[str, Wrapper] validation rejects raw scalars before\nthe wrapper's discriminator runs (same issue as the\nlocale-keyed candidate fields). NEVER returned by\n/v1/guest/attempts/* endpoints." }, "scoringRubric": { "type": "string", "description": "Recruiter-only. Free-form scoring rubric the AI evaluator uses\nfor `open-text`. NEVER returned by guest endpoints." } } } }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "AssessmentRelationshipsSchema", "type": "object", "properties": { "candidates": { "title": "AssessmentRelationshipsCandidatesSchema", "description": "Candidate-mode assessments stamp the candidates they screen; to-many on rows and on the wire.", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "AssessmentRelationshipsCandidatesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "job": { "title": "AssessmentRelationshipsJobSchema", "type": "object", "properties": { "data": { "title": "AssessmentRelationshipsJobDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } }, { "type": "function", "function": { "name": "assessments_options", "description": "Assessments Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_assessment", "description": "Show Assessment", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_assessment", "description": "Update Assessment", "parameters": { "title": "UpdateAssessmentRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateAssessmentRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "assessments" ] }, "id": { "type": "string" }, "attributes": { "title": "AssessmentAttributesSchema", "description": "Template-only attributes for an assessment. The candidate's run of an\nassessment (answers, scores, evaluation, proctoring) lives on the\nAttempt resource - see AttemptAttributesSchema.", "type": "object", "properties": { "status": { "type": "string", "description": "Template lifecycle. Candidate-side state (inProgress/submitted/\nevaluated/etc.) lives on attempts. `pending` is a transient state\nset when the AI Generate Step Function is in flight - the row\nflips to `active` once questions land. `accepted` = the ReCop\napproved this assessment at the operator gate (Create Job From\nBrief, gate 2); set by the job:accept-artifacts workflow action.", "enum": [ "draft", "active", "accepted", "archived", "failed", "pending" ] }, "duration": { "type": "integer", "description": "Time limit for the candidate to complete the assessment, in minutes. Defaults to 30." }, "antiCheatingLevel": { "type": "string", "enum": [ "TOLERANT", "MODERATE", "RIGOROUS" ] }, "passingScore": { "type": "number", "description": "Score threshold (0-100) for `evaluation.passed=true` on attempts of this template. Defaults to 60." }, "languageCode": { "type": "string", "description": "Default language tag used when the candidate UI doesn't specify one (e.g. 'en-US', 'pl-PL')." }, "name": { "type": "object", "description": "Multilingual template name. Keys are locale tags, values are the localized title.", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "description": "Multilingual template description shown to the candidate before they start.", "additionalProperties": { "type": "string" } }, "questions": { "type": "array", "description": "Question bank. See QuestionSchema for per-type schemas.", "items": { "title": "QuestionSchema", "description": "A single assessment question. Eight question types - the optional\nfields below are interpreted based on `type`. See\n`Question.value` shapes in AnswerSchema for what the candidate\nsends back per type.\n\nSECURITY: `answerKey`, `scoringRubric`, and `options[].isCorrect`\nare stripped server-side before responses are returned to candidates\nvia /v1/guest/attempts/* - they are recruiter-only fields.", "type": "object", "required": [ "questionId", "type" ], "properties": { "questionId": { "type": "string", "description": "Stable identifier (e.g. 'q1'). Candidates' answers reference this." }, "type": { "type": "string", "enum": [ "single-choice", "multiple-choice", "scale", "open-text", "ranking", "situational-judgment", "file-upload", "video-recording" ] }, "category": { "type": "string", "description": "Free-form tag for analytics (e.g. 'soft-skills', 'hard-skills', 'general')." }, "difficulty": { "type": "string", "enum": [ "easy", "medium", "hard" ] }, "points": { "type": "number", "description": "Maximum score for this question. Defaults to 1." }, "required": { "type": "boolean" }, "text": { "type": "object", "description": "Multilingual question text.", "additionalProperties": { "type": "string" } }, "options": { "type": "array", "description": "Choices for single-choice / multiple-choice / ranking /\nsituational-judgment. Canonical shape is\n`{ id, text: { locale: string }, isCorrect?: bool }`. Bare\nlocale-map options exist in legacy data but are deprecated.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable option id - candidates' answers reference this." }, "text": { "type": "object", "additionalProperties": { "type": "string" } }, "isCorrect": { "type": "boolean", "description": "Recruiter-only. Stripped server-side from guest responses." } } } }, "scaleMin": { "type": "integer", "description": "Lower bound for `scale` type questions." }, "scaleMax": { "type": "integer", "description": "Upper bound for `scale` type questions." }, "scaleLabels": { "type": "object", "description": "Optional labels per step value, multilingual.\n`{ \"1\": { \"en-US\": \"Strongly disagree\" }, \"5\": { \"en-US\": \"Strongly agree\" } }`.", "additionalProperties": { "type": "object", "additionalProperties": { "type": "string" } } }, "placeholder": { "type": "object", "description": "Multilingual placeholder text for `open-text` questions.", "additionalProperties": { "type": "string" } }, "scenario": { "type": "object", "description": "Multilingual scenario body for `situational-judgment` questions.", "additionalProperties": { "type": "string" } }, "acceptedFormats": { "type": "array", "description": "Accepted MIME or extension list for `file-upload` (e.g. ['.pdf', '.png']).", "items": { "type": "string" } }, "maxDuration": { "type": "integer", "description": "Maximum recording length in seconds for `video-recording`." }, "maxAttempts": { "type": "integer", "description": "Maximum recording retakes the candidate may use on `video-recording`." }, "explanation": { "type": "object", "description": "Multilingual explanation shown post-submission on review screens.", "additionalProperties": { "type": "string" } }, "answerKey": { "description": "Recruiter-only. Shape depends on questionType:\n single-choice -> string (option id)\n multiple-choice -> string[] (option ids)\n ranking -> string[] (option ids in order)\n situational-judgment -> { best: string, worst: string }\n scale / open-text -> not used (use scoringRubric)\nType intentionally left unconstrained (Any) - the variant\nshapes resist a oneOf wrapper because pydantic's outer\nDict[str, Wrapper] validation rejects raw scalars before\nthe wrapper's discriminator runs (same issue as the\nlocale-keyed candidate fields). NEVER returned by\n/v1/guest/attempts/* endpoints." }, "scoringRubric": { "type": "string", "description": "Recruiter-only. Free-form scoring rubric the AI evaluator uses\nfor `open-text`. NEVER returned by guest endpoints." } } } }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_assessment", "description": "Delete Assessment", "parameters": { "type": "object", "properties": { "permanentDelete": { "type": "string", "description": "When `true`, hard-delete the row. Otherwise sets status to archived.", "enum": [ "true", "false" ] } } } } }, { "type": "function", "function": { "name": "assessment_options", "description": "Assessment Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "create_attempt", "description": "Create Attempt", "parameters": { "title": "CreateAttemptRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateAttemptRequestBodyData", "type": "object", "required": [ "type", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "attempts" ] }, "attributes": { "title": "AttemptAttributesSchema", "type": "object", "properties": { "status": { "type": "string", "description": "Attempt lifecycle. Set server-side; only `submitted` is candidate-writable (via guest PATCH).", "enum": [ "pending", "inProgress", "submitted", "evaluated", "reviewed", "anonymized", "failed" ] }, "languageCode": { "type": "string", "description": "Locale the candidate is taking the assessment in (e.g. 'en-US')." }, "candidateName": { "type": "string", "description": "Candidate's display name, denormalised from the candidate row\nat attempt-create time. Lets the guest endpoint render\n\"Hello {name}\" without granting the guest IAM role candidate\ntable access. Snapshot - reflects the name as of attempt\ncreation; not kept in sync if the candidate is later renamed." }, "candidateEmail": { "type": "string", "description": "Candidate's email, denormalised from the candidate row at\nattempt-create time. Same rationale as candidateName." }, "jobTitle": { "type": "object", "additionalProperties": true, "description": "Job title denormalised from the job's multilingual title at\nattempt-create time. Multilingual dict keyed by locale\n(e.g. {\"en-US\": \"Senior Engineer\", \"pl-PL\": \"Starszy Inżynier\"});\nFE resolves against attempt.languageCode. Absent when the\nattempt has no job FK." }, "assessmentTitle": { "type": "object", "additionalProperties": true, "description": "Assessment template title denormalised from the template's\nmultilingual `name` field at attempt-create time. Same shape\nas jobTitle. Filled in by the attempt DAL from the template\nif the create request omits it." }, "answers": { "type": "array", "description": "Candidate's answers, one per attempted question. See AnswerSchema.", "items": { "title": "AnswerSchema", "description": "A candidate's answer to one question. The `value` shape depends\non the question type - branch on `questionType` to know how to\nread it. File uploads (file-upload / video-recording question\ntypes) live in the separate `files` array, NOT in `value`. This\nmirrors the wire shape used by /v1/guest/attempts/{id} PATCH\nand avoids OpenAPI generator collisions on multiple array\nvariants in a single oneOf.", "type": "object", "required": [ "questionId" ], "properties": { "questionId": { "type": "string", "description": "References QuestionSchema.questionId." }, "questionType": { "type": "string", "description": "Mirror of the question's type for client-side discrimination.", "enum": [ "single-choice", "multiple-choice", "scale", "open-text", "ranking", "situational-judgment", "file-upload", "video-recording" ] }, "value": { "description": "Non-file answer payload. Discriminated by questionType:\n single-choice -> string (option id)\n multiple-choice -> string[] (option ids)\n scale -> number\n open-text -> string\n ranking -> string[] (option ids in order)\n situational-judgment -> { best: string; worst: string }\n file-upload -> usually empty / null (use `files`)\n video-recording -> usually empty / null (use `files`)", "oneOf": [ { "type": "string", "description": "single-choice / open-text" }, { "type": "number", "description": "scale" }, { "type": "array", "items": { "type": "string" }, "description": "multiple-choice / ranking - array of option ids" }, { "type": "object", "description": "situational-judgment", "required": [ "best", "worst" ], "properties": { "best": { "type": "string" }, "worst": { "type": "string" } } } ] }, "files": { "type": "array", "description": "File / video uploads for `file-upload` and `video-recording`\nquestion types. Empty for all other types. Files are uploaded\nvia presigned PUT to S3 first; this carries the resulting\nreferences.", "items": { "title": "AnswerFileSchema", "description": "File reference for upload-type answers (file-upload /\nvideo-recording question types). The candidate UI obtains\n`fileKey` from POST /v1/guest/attempts/uploads, PUTs the file\nto S3 via the presigned URL returned alongside it, then\nincludes a reference like `{fileKey, fileName, contentType,\nsize}` here on the guest PATCH submission. Wire field names\nmatch what file:process and the eval Lambda's\n_enrich_answers_with_file_content expect (fileKey, not\nfileUrl - the S3 path is server-side only).", "type": "object", "properties": { "fileKey": { "type": "string", "description": "S3 key in the attempt bucket. Returned by POST /v1/guest/attempts/uploads as data.attributes.fileKey; FE echoes it here." }, "fileName": { "type": "string", "description": "Candidate-supplied original file name (display + audit trail)." }, "contentType": { "type": "string" }, "size": { "type": "integer", "description": "Bytes." } } } } } } }, "evaluation": { "title": "AttemptEvaluationSchema", "description": "AI scoring output. Populated by the evaluation Step Function\nafter the candidate submits. Hidden from the candidate response\nwhile status is below `evaluated`.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "overallScore": { "type": "number", "description": "Aggregate score 0-100." }, "passingScore": { "type": "number", "description": "Threshold copied from the template at evaluation time." }, "passed": { "type": "boolean" }, "perQuestion": { "type": "array", "items": { "type": "object", "required": [ "questionId", "score" ], "properties": { "questionId": { "type": "string" }, "score": { "type": "number" }, "maxScore": { "type": "number" }, "feedback": { "type": "string", "description": "1-2 sentence explanation in the candidate's language." }, "rubricMatched": { "type": "array", "items": { "type": "string" }, "description": "Recruiter-only. Stripped from guest responses." } } } }, "summary": { "type": "string", "description": "AI-generated 2-3 paragraph plain-language summary of the candidate's performance." }, "evaluatedAt": { "type": "string", "format": "date-time" }, "evaluatorVersion": { "type": "string" }, "error": { "type": "string", "description": "Set only when status=failed." } } }, "proctoring": { "title": "AttemptProctoringSchema", "description": "Anti-cheat telemetry collected by the candidate UI. Not used to block, only to inform recruiters.", "type": "object", "properties": { "tabSwitches": { "type": "integer" }, "pasteEvents": { "type": "integer" }, "focusLost": { "type": "integer", "description": "Total milliseconds the window was unfocused." }, "suspiciousFlags": { "type": "array", "items": { "type": "string" } } } }, "fileResults": { "type": "array", "description": "File-extraction results, one entry per file that\nfile:process processed during the assessment workflow's\nprocess_attachments step. Stamped onto the attempt by\nthe workflow's `attempt:trigger_evaluation` action right\nbefore /reevaluate fires. The eval Lambda joins these\nonto answers[i].files[i] by fileKey so the AI evaluator\nsees extracted content (transcripts / slide text / OCR)\nalongside the candidate's text answer for the same\nquestion. Locale value type left as Any because each\nfile:process emits a different shape per content type\n(PDF text, video transcript, etc).", "items": { "type": "object", "additionalProperties": true } }, "startedAt": { "type": "string", "format": "date-time", "description": "When the candidate first opened the attempt link (status pending->inProgress)." }, "submittedAt": { "type": "string", "format": "date-time", "description": "When the candidate finalised their answers (status inProgress->submitted)." }, "evaluatedAt": { "type": "string", "format": "date-time", "description": "When the AI evaluator wrote the evaluation block (status submitted->evaluated)." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Hard cutoff for the candidate to start. After this, /v1/guest/attempts rejects with 410-style errors." }, "durationMinutes": { "type": "integer", "description": "Time limit for the candidate to complete the attempt. Inherited from the template by default." }, "evaluatorVersion": { "type": "string", "description": "Identifier of the AI scorer that produced the evaluation (e.g. 'gpt-5-mini-v1'). Bumped on re-evaluate." }, "assessmentId": { "type": "string", "description": "FK to the assessment template - same id as relationships.assessment.data.id, exposed flat for filter convenience." }, "candidateId": { "type": "string", "description": "FK to the candidate - same id as relationships.candidate.data.id." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "AttemptRelationshipsSchema", "type": "object", "properties": { "assessment": { "title": "AttemptRelationshipsAssessmentSchema", "type": "object", "properties": { "data": { "title": "AttemptRelationshipsAssessmentDataSchema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "assessments" ] }, "id": { "type": "string" } } } }, "description": "FK to the template this attempt is a run of." }, "candidate": { "title": "AttemptRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "title": "AttemptRelationshipsCandidateDataSchema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "candidates" ] }, "id": { "type": "string" } } } } }, "job": { "title": "AttemptRelationshipsJobSchema", "type": "object", "properties": { "data": { "title": "AttemptRelationshipsJobDataSchema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "jobs" ] }, "id": { "type": "string" } } } }, "description": "Denormalised from the assessment template - the role this attempt is screening for." }, "report": { "title": "AttemptRelationshipsReportSchema", "type": "object", "properties": { "data": { "title": "AttemptRelationshipsReportDataSchema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "files" ] }, "id": { "type": "string" } } } }, "description": "Generated PDF report for this attempt's evaluation. Populated post-evaluation." }, "files": { "title": "AttemptRelationshipsFilesSchema", "type": "object", "description": "FileResources attached to this attempt - one per file the\ncandidate uploaded as a `file-upload` or `video-recording`\nanswer. Populated by the workflow's `trigger_evaluation`\nstep after `process_attachments` registers each file with\nthe file service. Use `?include=files` on `showAttempt` /\n`showGuestAttempt` to sideload the FileResources in\n`included[]` (single round-trip preview).\nThe answer-to-file mapping lives on `FileResource.meta.questionId`\n(set at `file:process` time), not on AnswerFileSchema -\nrelated-resource IDs in attributes would violate JSON:API.", "properties": { "data": { "type": "array", "items": { "title": "AttemptRelationshipsFilesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "list_attempts", "description": "List Attempts", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Filter by attempt status.", "enum": [ "pending", "inProgress", "submitted", "evaluated", "reviewed", "anonymized", "failed" ] }, "filterAssessmentId": { "type": "string", "description": "Filter by assessment template id." }, "filterCandidateId": { "type": "string", "description": "Filter by candidate id." }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "attempts_options", "description": "Attempts Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_attempt", "description": "Show Attempt", "parameters": { "type": "object", "properties": { "include": { "type": "string", "description": "Comma-separated list of relationships to sideload. Currently\nsupports `files`. Sideloaded resources land in `included[]`.\nOmit (or pass empty) for a relationships-only response." } } } } }, { "type": "function", "function": { "name": "update_attempt", "description": "Update Attempt", "parameters": { "title": "UpdateAttemptRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateAttemptRequestBodyData", "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "attempts" ] }, "id": { "type": "string" }, "attributes": { "title": "AttemptAttributesSchema", "type": "object", "properties": { "status": { "type": "string", "description": "Attempt lifecycle. Set server-side; only `submitted` is candidate-writable (via guest PATCH).", "enum": [ "pending", "inProgress", "submitted", "evaluated", "reviewed", "anonymized", "failed" ] }, "languageCode": { "type": "string", "description": "Locale the candidate is taking the assessment in (e.g. 'en-US')." }, "candidateName": { "type": "string", "description": "Candidate's display name, denormalised from the candidate row\nat attempt-create time. Lets the guest endpoint render\n\"Hello {name}\" without granting the guest IAM role candidate\ntable access. Snapshot - reflects the name as of attempt\ncreation; not kept in sync if the candidate is later renamed." }, "candidateEmail": { "type": "string", "description": "Candidate's email, denormalised from the candidate row at\nattempt-create time. Same rationale as candidateName." }, "jobTitle": { "type": "object", "additionalProperties": true, "description": "Job title denormalised from the job's multilingual title at\nattempt-create time. Multilingual dict keyed by locale\n(e.g. {\"en-US\": \"Senior Engineer\", \"pl-PL\": \"Starszy Inżynier\"});\nFE resolves against attempt.languageCode. Absent when the\nattempt has no job FK." }, "assessmentTitle": { "type": "object", "additionalProperties": true, "description": "Assessment template title denormalised from the template's\nmultilingual `name` field at attempt-create time. Same shape\nas jobTitle. Filled in by the attempt DAL from the template\nif the create request omits it." }, "answers": { "type": "array", "description": "Candidate's answers, one per attempted question. See AnswerSchema.", "items": { "title": "AnswerSchema", "description": "A candidate's answer to one question. The `value` shape depends\non the question type - branch on `questionType` to know how to\nread it. File uploads (file-upload / video-recording question\ntypes) live in the separate `files` array, NOT in `value`. This\nmirrors the wire shape used by /v1/guest/attempts/{id} PATCH\nand avoids OpenAPI generator collisions on multiple array\nvariants in a single oneOf.", "type": "object", "required": [ "questionId" ], "properties": { "questionId": { "type": "string", "description": "References QuestionSchema.questionId." }, "questionType": { "type": "string", "description": "Mirror of the question's type for client-side discrimination.", "enum": [ "single-choice", "multiple-choice", "scale", "open-text", "ranking", "situational-judgment", "file-upload", "video-recording" ] }, "value": { "description": "Non-file answer payload. Discriminated by questionType:\n single-choice -> string (option id)\n multiple-choice -> string[] (option ids)\n scale -> number\n open-text -> string\n ranking -> string[] (option ids in order)\n situational-judgment -> { best: string; worst: string }\n file-upload -> usually empty / null (use `files`)\n video-recording -> usually empty / null (use `files`)", "oneOf": [ { "type": "string", "description": "single-choice / open-text" }, { "type": "number", "description": "scale" }, { "type": "array", "items": { "type": "string" }, "description": "multiple-choice / ranking - array of option ids" }, { "type": "object", "description": "situational-judgment", "required": [ "best", "worst" ], "properties": { "best": { "type": "string" }, "worst": { "type": "string" } } } ] }, "files": { "type": "array", "description": "File / video uploads for `file-upload` and `video-recording`\nquestion types. Empty for all other types. Files are uploaded\nvia presigned PUT to S3 first; this carries the resulting\nreferences.", "items": { "title": "AnswerFileSchema", "description": "File reference for upload-type answers (file-upload /\nvideo-recording question types). The candidate UI obtains\n`fileKey` from POST /v1/guest/attempts/uploads, PUTs the file\nto S3 via the presigned URL returned alongside it, then\nincludes a reference like `{fileKey, fileName, contentType,\nsize}` here on the guest PATCH submission. Wire field names\nmatch what file:process and the eval Lambda's\n_enrich_answers_with_file_content expect (fileKey, not\nfileUrl - the S3 path is server-side only).", "type": "object", "properties": { "fileKey": { "type": "string", "description": "S3 key in the attempt bucket. Returned by POST /v1/guest/attempts/uploads as data.attributes.fileKey; FE echoes it here." }, "fileName": { "type": "string", "description": "Candidate-supplied original file name (display + audit trail)." }, "contentType": { "type": "string" }, "size": { "type": "integer", "description": "Bytes." } } } } } } }, "evaluation": { "title": "AttemptEvaluationSchema", "description": "AI scoring output. Populated by the evaluation Step Function\nafter the candidate submits. Hidden from the candidate response\nwhile status is below `evaluated`.", "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "running", "done", "failed" ] }, "overallScore": { "type": "number", "description": "Aggregate score 0-100." }, "passingScore": { "type": "number", "description": "Threshold copied from the template at evaluation time." }, "passed": { "type": "boolean" }, "perQuestion": { "type": "array", "items": { "type": "object", "required": [ "questionId", "score" ], "properties": { "questionId": { "type": "string" }, "score": { "type": "number" }, "maxScore": { "type": "number" }, "feedback": { "type": "string", "description": "1-2 sentence explanation in the candidate's language." }, "rubricMatched": { "type": "array", "items": { "type": "string" }, "description": "Recruiter-only. Stripped from guest responses." } } } }, "summary": { "type": "string", "description": "AI-generated 2-3 paragraph plain-language summary of the candidate's performance." }, "evaluatedAt": { "type": "string", "format": "date-time" }, "evaluatorVersion": { "type": "string" }, "error": { "type": "string", "description": "Set only when status=failed." } } }, "proctoring": { "title": "AttemptProctoringSchema", "description": "Anti-cheat telemetry collected by the candidate UI. Not used to block, only to inform recruiters.", "type": "object", "properties": { "tabSwitches": { "type": "integer" }, "pasteEvents": { "type": "integer" }, "focusLost": { "type": "integer", "description": "Total milliseconds the window was unfocused." }, "suspiciousFlags": { "type": "array", "items": { "type": "string" } } } }, "fileResults": { "type": "array", "description": "File-extraction results, one entry per file that\nfile:process processed during the assessment workflow's\nprocess_attachments step. Stamped onto the attempt by\nthe workflow's `attempt:trigger_evaluation` action right\nbefore /reevaluate fires. The eval Lambda joins these\nonto answers[i].files[i] by fileKey so the AI evaluator\nsees extracted content (transcripts / slide text / OCR)\nalongside the candidate's text answer for the same\nquestion. Locale value type left as Any because each\nfile:process emits a different shape per content type\n(PDF text, video transcript, etc).", "items": { "type": "object", "additionalProperties": true } }, "startedAt": { "type": "string", "format": "date-time", "description": "When the candidate first opened the attempt link (status pending->inProgress)." }, "submittedAt": { "type": "string", "format": "date-time", "description": "When the candidate finalised their answers (status inProgress->submitted)." }, "evaluatedAt": { "type": "string", "format": "date-time", "description": "When the AI evaluator wrote the evaluation block (status submitted->evaluated)." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Hard cutoff for the candidate to start. After this, /v1/guest/attempts rejects with 410-style errors." }, "durationMinutes": { "type": "integer", "description": "Time limit for the candidate to complete the attempt. Inherited from the template by default." }, "evaluatorVersion": { "type": "string", "description": "Identifier of the AI scorer that produced the evaluation (e.g. 'gpt-5-mini-v1'). Bumped on re-evaluate." }, "assessmentId": { "type": "string", "description": "FK to the assessment template - same id as relationships.assessment.data.id, exposed flat for filter convenience." }, "candidateId": { "type": "string", "description": "FK to the candidate - same id as relationships.candidate.data.id." }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "AttemptRelationshipsSchema", "type": "object", "properties": { "assessment": { "title": "AttemptRelationshipsAssessmentSchema", "type": "object", "properties": { "data": { "title": "AttemptRelationshipsAssessmentDataSchema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "assessments" ] }, "id": { "type": "string" } } } }, "description": "FK to the template this attempt is a run of." }, "candidate": { "title": "AttemptRelationshipsCandidateSchema", "type": "object", "properties": { "data": { "title": "AttemptRelationshipsCandidateDataSchema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "candidates" ] }, "id": { "type": "string" } } } } }, "job": { "title": "AttemptRelationshipsJobSchema", "type": "object", "properties": { "data": { "title": "AttemptRelationshipsJobDataSchema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "jobs" ] }, "id": { "type": "string" } } } }, "description": "Denormalised from the assessment template - the role this attempt is screening for." }, "report": { "title": "AttemptRelationshipsReportSchema", "type": "object", "properties": { "data": { "title": "AttemptRelationshipsReportDataSchema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "files" ] }, "id": { "type": "string" } } } }, "description": "Generated PDF report for this attempt's evaluation. Populated post-evaluation." }, "files": { "title": "AttemptRelationshipsFilesSchema", "type": "object", "description": "FileResources attached to this attempt - one per file the\ncandidate uploaded as a `file-upload` or `video-recording`\nanswer. Populated by the workflow's `trigger_evaluation`\nstep after `process_attachments` registers each file with\nthe file service. Use `?include=files` on `showAttempt` /\n`showGuestAttempt` to sideload the FileResources in\n`included[]` (single round-trip preview).\nThe answer-to-file mapping lives on `FileResource.meta.questionId`\n(set at `file:process` time), not on AnswerFileSchema -\nrelated-resource IDs in attributes would violate JSON:API.", "properties": { "data": { "type": "array", "items": { "title": "AttemptRelationshipsFilesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } }, "meta": { "type": "object", "description": "Free-form metadata. The assessment workflow uses\nmeta.runContext to stash the runId/shardId of the\nparking long-running step so the eventbus resumer\ncan wake the workflow on ATTEMPT_SUBMITTED.", "additionalProperties": true } } } } } } }, { "type": "function", "function": { "name": "delete_attempt", "description": "Delete Attempt", "parameters": { "type": "object", "properties": { "permanentDelete": { "type": "string", "description": "permanentDelete parameter", "enum": [ "true", "false" ] } } } } }, { "type": "function", "function": { "name": "attempt_options", "description": "Attempt Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "reevaluate_attempt", "description": "Reevaluate Attempt", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "reevaluate_attempt_options", "description": "Reevaluate Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "upload_guest_attempt_file", "description": "Upload Attempt File (Guest)", "parameters": { "title": "UploadGuestAttemptFileRequestBody", "type": "object", "required": [ "tenantId", "accessToken", "attemptId", "fileName", "contentType" ], "properties": { "tenantId": { "type": "string" }, "accessToken": { "type": "string", "description": "Per-attempt token (same value as meta.accessToken on other guest endpoints)." }, "attemptId": { "type": "string" }, "fileName": { "type": "string", "description": "Candidate-supplied file name (no path traversal). Used for the audit trail and extension fallback." }, "contentType": { "type": "string", "description": "MIME type. Server prefers a known value (mapped to canonical extension) but accepts unknown types - file:process derives extension from fileName." }, "questionId": { "type": "string", "description": "Optional question id this upload is for. Used for S3 key partitioning + downstream join hint; not auth-relevant." }, "durationMs": { "type": "integer", "format": "int64", "minimum": 0, "description": "Optional client-measured recording duration in milliseconds.\nSet by the candidate FE for video-recording / audio-recording\nquestions where MediaRecorder doesn't finalize the container's\nDuration element. Used as a fallback when ffprobe / re-mux\ncan't derive duration from the file alone. Backend persists\nit to attempt.meta.pendingUploads[fileKey] and surfaces it\nvia attempt:show -> fileRefs so the workflow's process_attachments\nstep forwards it to file:process; the file row then carries\nattributes.durationSeconds + meta.durationSource='client'\nuntil ffmpeg re-mux overwrites with a more reliable value." } } } } }, { "type": "function", "function": { "name": "guest_attempt_upload_options", "description": "Guest Attempt Upload Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "start_guest_attempt", "description": "Start Guest Attempt", "parameters": { "title": "StartGuestAttemptRequestBody", "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "title": "StartGuestAttemptRequestBodyData", "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "attempts" ] }, "id": { "type": "string" } } }, "meta": { "title": "GuestMetaSchema", "description": "Auth context for unauthenticated /v1/guest/attempts/* writes.\ntenantId scopes the call; accessToken is the per-attempt token\nissued at create time. Token mismatch returns 404 (intentionally\nindistinguishable from \"attempt not found\" so we don't leak\nattempt existence).", "type": "object", "required": [ "tenantId", "accessToken" ], "properties": { "tenantId": { "type": "string" }, "accessToken": { "type": "string" } } } } } } }, { "type": "function", "function": { "name": "guest_attempts_options", "description": "Guest Attempts Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_guest_attempt", "description": "Show Guest Attempt", "parameters": { "type": "object", "properties": { "tenantId": { "type": "string", "description": "tenantId parameter" }, "token": { "type": "string", "description": "token parameter" }, "include": { "type": "string", "description": "Comma-separated list of relationships to sideload. Currently\nsupports `files`. Sideloaded resources land in `included[]`." } }, "required": [ "tenantId", "token" ] } } }, { "type": "function", "function": { "name": "update_guest_attempt", "description": "Update Guest Attempt", "parameters": { "title": "UpdateGuestAttemptRequestBody", "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "title": "UpdateGuestAttemptRequestBodyData", "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "attempts" ] }, "id": { "type": "string" }, "attributes": { "title": "UpdateGuestAttemptRequestBodyDataAttributes", "type": "object", "properties": { "answers": { "type": "array", "description": "Per-question answers. Each entry follows the\ncanonical AnswerSchema with `value` as the\ntype-discriminated payload (string / number /\nstring[] / situational-judgment object).", "items": { "title": "AnswerSchema", "description": "A candidate's answer to one question. The `value` shape depends\non the question type - branch on `questionType` to know how to\nread it. File uploads (file-upload / video-recording question\ntypes) live in the separate `files` array, NOT in `value`. This\nmirrors the wire shape used by /v1/guest/attempts/{id} PATCH\nand avoids OpenAPI generator collisions on multiple array\nvariants in a single oneOf.", "type": "object", "required": [ "questionId" ], "properties": { "questionId": { "type": "string", "description": "References QuestionSchema.questionId." }, "questionType": { "type": "string", "description": "Mirror of the question's type for client-side discrimination.", "enum": [ "single-choice", "multiple-choice", "scale", "open-text", "ranking", "situational-judgment", "file-upload", "video-recording" ] }, "value": { "description": "Non-file answer payload. Discriminated by questionType:\n single-choice -> string (option id)\n multiple-choice -> string[] (option ids)\n scale -> number\n open-text -> string\n ranking -> string[] (option ids in order)\n situational-judgment -> { best: string; worst: string }\n file-upload -> usually empty / null (use `files`)\n video-recording -> usually empty / null (use `files`)", "oneOf": [ { "type": "string", "description": "single-choice / open-text" }, { "type": "number", "description": "scale" }, { "type": "array", "items": { "type": "string" }, "description": "multiple-choice / ranking - array of option ids" }, { "type": "object", "description": "situational-judgment", "required": [ "best", "worst" ], "properties": { "best": { "type": "string" }, "worst": { "type": "string" } } } ] }, "files": { "type": "array", "description": "File / video uploads for `file-upload` and `video-recording`\nquestion types. Empty for all other types. Files are uploaded\nvia presigned PUT to S3 first; this carries the resulting\nreferences.", "items": { "title": "AnswerFileSchema", "description": "File reference for upload-type answers (file-upload /\nvideo-recording question types). The candidate UI obtains\n`fileKey` from POST /v1/guest/attempts/uploads, PUTs the file\nto S3 via the presigned URL returned alongside it, then\nincludes a reference like `{fileKey, fileName, contentType,\nsize}` here on the guest PATCH submission. Wire field names\nmatch what file:process and the eval Lambda's\n_enrich_answers_with_file_content expect (fileKey, not\nfileUrl - the S3 path is server-side only).", "type": "object", "properties": { "fileKey": { "type": "string", "description": "S3 key in the attempt bucket. Returned by POST /v1/guest/attempts/uploads as data.attributes.fileKey; FE echoes it here." }, "fileName": { "type": "string", "description": "Candidate-supplied original file name (display + audit trail)." }, "contentType": { "type": "string" }, "size": { "type": "integer", "description": "Bytes." } } } } } } }, "proctoring": { "title": "AttemptProctoringSchema", "description": "Anti-cheat telemetry collected by the candidate UI. Not used to block, only to inform recruiters.", "type": "object", "properties": { "tabSwitches": { "type": "integer" }, "pasteEvents": { "type": "integer" }, "focusLost": { "type": "integer", "description": "Total milliseconds the window was unfocused." }, "suspiciousFlags": { "type": "array", "items": { "type": "string" } } } }, "status": { "type": "string", "description": "Only `submitted` is candidate-writable through\nthis path. Other transitions (evaluated, etc.)\nare server-set.", "enum": [ "submitted" ] } } } } }, "meta": { "title": "GuestMetaSchema", "description": "Auth context for unauthenticated /v1/guest/attempts/* writes.\ntenantId scopes the call; accessToken is the per-attempt token\nissued at create time. Token mismatch returns 404 (intentionally\nindistinguishable from \"attempt not found\" so we don't leak\nattempt existence).", "type": "object", "required": [ "tenantId", "accessToken" ], "properties": { "tenantId": { "type": "string" }, "accessToken": { "type": "string" } } } } } } }, { "type": "function", "function": { "name": "guest_attempt_options", "description": "Guest Attempt Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_actions", "description": "List Actions", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Filter by status (active, inactive).", "enum": [ "active", "inactive" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_action", "description": "Create Action", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_action", "description": "Show Action", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_action", "description": "Update Action", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "delete_action", "description": "Delete Action", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_workflows", "description": "List Workflows", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Filter by status (active, inactive, draft, archived).", "enum": [ "active", "inactive", "draft", "archived" ] }, "filterName": { "type": "string", "description": "Filter by workflow name." }, "filterCategory": { "type": "string", "description": "Filter by category (sourcing, screening, assessment, onboarding, operational, general). Uses CategoryIndex GSI - efficient at scale.", "enum": [ "sourcing", "screening", "assessment", "onboarding", "operational", "general" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_workflow", "description": "Create Workflow", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_workflow", "description": "Show Workflow", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_workflow", "description": "Update Workflow", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "delete_workflow", "description": "Delete Workflow", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_triggers", "description": "List Triggers", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Filter by status (active, inactive).", "enum": [ "active", "inactive" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_trigger", "description": "Create Trigger", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_trigger", "description": "Show Trigger", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_trigger", "description": "Update Trigger", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "delete_trigger", "description": "Delete Trigger", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_runs", "description": "List Runs", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Filter by status (pending, running, completed, failed, aborted).", "enum": [ "pending", "running", "completed", "failed", "aborted", "paused" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_run", "description": "Create Run", "parameters": { "title": "CreateRunRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateRunRequestBodyData", "type": "object", "required": [ "type", "attributes", "relationships" ], "properties": { "type": { "type": "string", "enum": [ "runs" ] }, "attributes": { "title": "RunAttributesSchema", "type": "object", "properties": { "triggerPayload": { "type": "object", "description": "The data payload for the workflow. Must include all required fields from the workflow requirements schema." } } }, "relationships": { "title": "RunRelationshipsSchema", "type": "object", "required": [ "workflow" ], "properties": { "workflow": { "type": "object", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "workflows" ] }, "id": { "type": "string", "description": "The workflow ID to run." } } } } } } } } } } } } }, { "type": "function", "function": { "name": "show_run", "description": "Show Run", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_run", "description": "Update Run", "parameters": { "title": "UpdateRunRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateRunRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "runs" ] }, "id": { "type": "string" }, "attributes": { "title": "UpdateRunAttributesSchema", "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "running", "aborted" ], "description": "Target status. 'running' redrives a failed/paused/completed run; 'aborted' cancels a pending/running run." }, "fromStep": { "type": "integer", "minimum": 0, "description": "Only valid when status=running. Zero-based index of the step to redrive from. All step results from this index onwards are discarded. If omitted, resumes from the last failed/paused step (legacy behavior)." } } } } } } } } }, { "type": "function", "function": { "name": "list_webhooks", "description": "List Webhooks", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns webhooks with the current status (active, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "archived" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_webhook", "description": "Create Webhook", "parameters": { "title": "CreateWebhookRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateWebhookRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "webhooks" ] }, "attributes": { "title": "WebhookAttributesSchema", "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "WebhookRelationshipsSchema", "type": "object" } } } } } } }, { "type": "function", "function": { "name": "webhooks_options", "description": "Webhooks Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_webhook", "description": "Show Webhook", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_webhook", "description": "Update Webhook", "parameters": { "title": "UpdateWebhookRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateWebhookRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "webhooks" ] }, "id": { "type": "string" }, "attributes": { "title": "WebhookAttributesSchema", "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_webhook", "description": "Delete Webhook", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "webhook_options", "description": "Webhook Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "recall_webhook", "description": "Recall.ai bot lifecycle webhook", "parameters": { "type": "object", "properties": { "event": { "type": "string", "description": "Recall lifecycle event type (e.g. bot.done, bot.in_call_recording, bot.fatal)." }, "data": { "type": "object" } } } } }, { "type": "function", "function": { "name": "recall_webhook_options", "description": "Recall webhook CORS preflight", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_finders", "description": "List Finders", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns finders with the current status (active, pending, completed, failed, archived). If not provided, the default value will be set to 'active'.", "enum": [ "active", "pending", "completed", "failed", "archived" ] }, "filterType": { "type": "string", "description": "Returns finders with the specified type (talents, candidates, jobs, emails, users, reports, briefs).", "enum": [ "talents", "candidates", "jobs", "emails", "users", "reports", "briefs" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_finder", "description": "Create Finder", "parameters": { "title": "CreateFinderRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateFinderRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "finders" ] }, "attributes": { "title": "FinderAttributesSchema", "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "The name of the finder search" }, "type": { "type": "string", "enum": [ "talents", "candidates", "jobs", "emails", "users", "reports", "briefs" ], "description": "The type of search to perform" }, "query": { "description": "Search query parameters sent to OpenSearch. Shape varies by finder `type` - see FinderQuery{Talents,Candidates,Jobs,Emails}Schema below for the per-type fields. Encoded as a free-form object, NOT a `oneOf`: the per-type shapes all share optional fields (notably `search`), and the type discriminator lives on the sibling `type` field (not inside `query`), so a oneOf cannot disambiguate them and fails deserialization with \"Multiple matches\". Clients build the dict matching the `type`.", "type": "object", "additionalProperties": true }, "results": { "title": "FinderResultsSchema", "type": "object", "description": "OpenSearch-shaped results attached to the finder record after the search runs. Hits array items carry whatever subset of the index schema was projected.", "properties": { "total": { "type": "integer", "description": "Count of matching documents before pagination." }, "hits": { "type": "array", "items": { "title": "FinderResultHitSchema", "type": "object", "description": "Single hit from the OpenSearch query. The `id` equals the underlying resource id (emailId, talentId, candidateId, jobId, ...) so the frontend can navigate directly to that resource. Additional fields vary by finder `type`.", "properties": { "id": { "type": "string", "description": "The underlying resource id (emailId / talentId / candidateId / jobId)." }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "created": { "type": "string" }, "shortCode": { "type": "string" } }, "additionalProperties": true } } } }, "status": { "type": "string", "enum": [ "active", "pending", "completed", "failed", "archived" ], "description": "The current status of the finder" }, "languageCode": { "type": "string", "description": "Language code for the finder (default en)" }, "settings": { "type": "object", "description": "Additional configuration settings" }, "source": { "type": "string", "description": "Source of the finder creation" }, "shortCode": { "type": "string", "description": "Unique short identifier" }, "ttl": { "type": "string", "description": "Time-to-live expiration timestamp (ISO 8601)" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } }, "relationships": { "title": "FinderRelationshipsSchema", "type": "object", "properties": { "jobs": { "title": "FinderRelationshipsJobsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "FinderRelationshipsJobsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "users": { "title": "FinderRelationshipsUsersSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "FinderRelationshipsUsersDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "talents": { "title": "FinderRelationshipsTalentsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "FinderRelationshipsTalentsDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } }, "candidates": { "title": "FinderRelationshipsCandidatesSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "title": "FinderRelationshipsCandidatesDataSchema", "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "finders_options", "description": "Finders Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_finder", "description": "Show Finder", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_finder", "description": "Update Finder", "parameters": { "title": "UpdateFinderRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateFinderRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "finders" ] }, "id": { "type": "string" }, "attributes": { "title": "FinderAttributesSchema", "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "The name of the finder search" }, "type": { "type": "string", "enum": [ "talents", "candidates", "jobs", "emails", "users", "reports", "briefs" ], "description": "The type of search to perform" }, "query": { "description": "Search query parameters sent to OpenSearch. Shape varies by finder `type` - see FinderQuery{Talents,Candidates,Jobs,Emails}Schema below for the per-type fields. Encoded as a free-form object, NOT a `oneOf`: the per-type shapes all share optional fields (notably `search`), and the type discriminator lives on the sibling `type` field (not inside `query`), so a oneOf cannot disambiguate them and fails deserialization with \"Multiple matches\". Clients build the dict matching the `type`.", "type": "object", "additionalProperties": true }, "results": { "title": "FinderResultsSchema", "type": "object", "description": "OpenSearch-shaped results attached to the finder record after the search runs. Hits array items carry whatever subset of the index schema was projected.", "properties": { "total": { "type": "integer", "description": "Count of matching documents before pagination." }, "hits": { "type": "array", "items": { "title": "FinderResultHitSchema", "type": "object", "description": "Single hit from the OpenSearch query. The `id` equals the underlying resource id (emailId, talentId, candidateId, jobId, ...) so the frontend can navigate directly to that resource. Additional fields vary by finder `type`.", "properties": { "id": { "type": "string", "description": "The underlying resource id (emailId / talentId / candidateId / jobId)." }, "tenantId": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "created": { "type": "string" }, "shortCode": { "type": "string" } }, "additionalProperties": true } } } }, "status": { "type": "string", "enum": [ "active", "pending", "completed", "failed", "archived" ], "description": "The current status of the finder" }, "languageCode": { "type": "string", "description": "Language code for the finder (default en)" }, "settings": { "type": "object", "description": "Additional configuration settings" }, "source": { "type": "string", "description": "Source of the finder creation" }, "shortCode": { "type": "string", "description": "Unique short identifier" }, "ttl": { "type": "string", "description": "Time-to-live expiration timestamp (ISO 8601)" }, "timestamps": { "title": "ResourceTimestampsSchema", "type": "object", "properties": { "created": { "type": "string", "format": "date-time" }, "modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_finder", "description": "Delete Finder", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "finder_options", "description": "Finder Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_notifications", "description": "List Notifications", "parameters": { "type": "object", "properties": { "filterStatus": { "type": "string", "description": "Returns notifications with the specified status (read, unread).", "enum": [ "read", "unread" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_notification", "description": "Create Notification", "parameters": { "title": "CreateNotificationRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "CreateNotificationRequestBodyData", "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "notifications" ] }, "attributes": { "title": "NotificationAttributesSchema", "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "description": "The notification title" }, "subtitle": { "type": "string", "description": "The notification subtitle" }, "category": { "type": "string", "description": "The notification category", "enum": [ "general", "task", "finder", "candidate", "file", "assessment" ], "default": "general" }, "status": { "type": "string", "description": "Read/unread status", "enum": [ "read", "unread" ], "default": "unread" }, "avatarIcon": { "type": "string", "description": "Tabler icon name for the notification avatar" }, "avatarText": { "type": "string", "description": "Text to display in the notification avatar" }, "avatarImage": { "type": "string", "description": "Image URL for the notification avatar" }, "avatarColor": { "type": "string", "description": "Color theme for the notification avatar", "default": "primary" }, "messageKey": { "type": "string", "description": "Identifier of the message to render, e.g. `user.pendingApproval`. The bell looks it up in the client's own dictionaries and substitutes messageParams, so the sentence is produced in whatever language the reader has set AT DISPLAY TIME - switching language re-renders the whole history, and adding a platform language needs no backend change and no migration of stored rows. Same shape the mobile platforms use natively (APNs loc-key/loc-args, FCM loc_key/loc_args). Absent on producers that have not migrated yet; `title`/`subtitle` remain the English fallback, so a client that does not recognise a key must fall back to them rather than render nothing." }, "messageParams": { "type": "object", "additionalProperties": true, "description": "Variable parts of the message, substituted into the dictionary entry for messageKey - e.g. {name, email} for `user.pendingApproval`. Names must match what the client dictionary expects: a mismatch surfaces as an untranslated placeholder, so the agreed keys and parameter names belong in the FE task, not in tribal memory." }, "created": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "modified": { "type": "string", "format": "date-time", "description": "Last modified timestamp" } } }, "relationships": { "title": "NotificationRelationshipsSchema", "type": "object", "description": "Declared in the WIRE shape, not the storage shape. Rows keep to-many entries as arrays, but transform_all_relationships serialises `users` to-ONE (RELATIONSHIP_TYPES says cardinality one) and renames it `user` - a spec written from the row therefore matches nothing and the generated client silently drops the whole relationship.", "properties": { "user": { "type": "object", "description": "Who the notification is FOR. Singular and to-one on the wire.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "subject": { "type": "object", "description": "What the notification is ABOUT - the target of the bell's deep link. Always this name, whatever the resource is, and it carries its own `type` so the client routes on that. Producers used to key this by resource type (`tasks`, `jobs`, ...), which cannot be declared here without enumerating every type any producer might ever use, so the typed client dropped all of them; it also collided with `user` outright when the subject was itself a user, overwriting the recipient. Absent when the notification is about nothing in particular.", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } }, "calls": { "title": "NotificationRelationshipsCallsSchema", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" } } } } } } } } } } } } } }, { "type": "function", "function": { "name": "notifications_options", "description": "Notifications Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "get_notification", "description": "Get Notification", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_notification", "description": "Update Notification", "parameters": { "title": "UpdateNotificationRequestBody", "type": "object", "required": [ "data" ], "properties": { "data": { "title": "UpdateNotificationRequestBodyData", "type": "object", "required": [ "type", "id", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "notifications" ] }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "read", "unread" ] } } } } } } } } }, { "type": "function", "function": { "name": "delete_notification", "description": "Delete Notification", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "notification_options", "description": "Notification Options", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_timelines", "description": "List Timelines", "parameters": { "type": "object", "properties": { "filterEntityKey": { "type": "string", "description": "Filter timeline entries by entity key prefix (e.g., \"jobs#entityId\")" }, "filterUserKey": { "type": "string", "description": "Filter timeline entries by user key prefix (e.g., \"userId\")" }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "cors_timelines", "description": "CORS support for Timelines", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "show_timeline", "description": "Show Timeline Entry", "parameters": { "type": "object", "properties": { "timelineId": { "type": "string", "description": "The timeline entry ID" } }, "required": [ "timelineId" ] } } }, { "type": "function", "function": { "name": "cors_timeline_entry", "description": "CORS support for Timeline Entry", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "rollback_timeline", "description": "Rollback Timeline Entry", "parameters": { "type": "object", "properties": { "timelineId": { "type": "string", "description": "The timeline entry ID to rollback to" } }, "required": [ "timelineId" ] } } }, { "type": "function", "function": { "name": "cors_timeline_rollback", "description": "CORS support for Timeline Rollback", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "list_calendars", "description": "List Calendars", "parameters": { "type": "object", "properties": { "filterOwnerId": { "type": "string", "description": "Filter by owner userId. Indexed via OwnerIndex." }, "filterOwnerType": { "type": "string", "description": "Filter by owner principal type. Today only `users` (reserved for shared / room calendars).", "enum": [ "users" ] }, "filterCreatedFrom": { "type": "string", "description": "Filters results to include only those created from the specified date and time. The value must be in ISO 8601 format." }, "filterCreatedTo": { "type": "string", "description": "Filters results to include only those created up to the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedFrom": { "type": "string", "description": "Filters results to include only those modified from the specified date and time. The value must be in ISO 8601 format." }, "filterModifiedTo": { "type": "string", "description": "Filters results to include only those modified up to the specified date and time. The value must be in ISO 8601 format." }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." }, "pageAfter": { "type": "string", "description": "Opaque base64-encoded cursor returned by a previous list response, used for forward cursor-based pagination. Pass the value verbatim; do not decode or mutate it." }, "pageBefore": { "type": "string", "description": "Returns the data encoded in Base64 format, used for cursor-based pagination" } } } } }, { "type": "function", "function": { "name": "create_calendar", "description": "Create Calendar", "parameters": { "title": "CreateCalendarRequestSchema", "type": "object", "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "calendars" ] }, "attributes": { "type": "object", "required": [ "ownerId" ], "properties": { "ownerId": { "type": "string" }, "ownerType": { "type": "string", "enum": [ "users" ] }, "name": { "type": "string" }, "color": { "type": "string" }, "timezone": { "type": "string" }, "maxConcurrentEvents": { "type": "integer" }, "workingHours": { "title": "CalendarWorkingHoursSchema", "type": "object", "description": "Recurring weekly schedule. days[] uses tokens (mon/tue/wed/thu/fri/sat/sun); startHour/endHour are local 24h numbers. Single type used by Calendar read/create/update so PATCH callers get the same autocomplete as readers.", "properties": { "timezone": { "type": "string" }, "days": { "type": "array", "items": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] } }, "startHour": { "type": "integer" }, "endHour": { "type": "integer" } } } } } } } } } } }, { "type": "function", "function": { "name": "show_calendar", "description": "Show Calendar", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_calendar", "description": "Update Calendar", "parameters": { "title": "UpdateCalendarRequestSchema", "type": "object", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "calendars" ] }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "archived" ] }, "timezone": { "type": "string" }, "maxConcurrentEvents": { "type": "integer" }, "workingHours": { "title": "CalendarWorkingHoursSchema", "type": "object", "description": "Recurring weekly schedule. days[] uses tokens (mon/tue/wed/thu/fri/sat/sun); startHour/endHour are local 24h numbers. Single type used by Calendar read/create/update so PATCH callers get the same autocomplete as readers.", "properties": { "timezone": { "type": "string" }, "days": { "type": "array", "items": { "type": "string", "enum": [ "mon", "tue", "wed", "thu", "fri", "sat", "sun" ] } }, "startHour": { "type": "integer" }, "endHour": { "type": "integer" } } } } } } } } } } }, { "type": "function", "function": { "name": "delete_calendar", "description": "Delete Calendar", "parameters": { "type": "object", "properties": { "permanentDelete": { "type": "string", "description": "Set to `true` for hard-delete.", "enum": [ "true", "false" ] } } } } }, { "type": "function", "function": { "name": "list_events", "description": "List Events", "parameters": { "type": "object", "properties": { "filterCalendarId": { "type": "string", "description": "Filter events in this calendar. Required for grid views." }, "filterAttendeeType": { "type": "string", "description": "Limit to events for this principal type (paired with filterAttendeeId).", "enum": [ "users", "candidates", "talents", "visitors" ] }, "filterAttendeeId": { "type": "string", "description": "Limit to events where this principal is an attendee." }, "filterDateFrom": { "type": "string", "description": "ISO 8601 lower bound on event startMs." }, "filterDateTo": { "type": "string", "description": "ISO 8601 upper bound on event startMs." }, "filterDateFromMs": { "type": "integer", "description": "Epoch milliseconds lower bound on event startMs." }, "filterDateToMs": { "type": "integer", "description": "Epoch milliseconds upper bound on event startMs." }, "filterEventType": { "type": "string", "description": "Filter by event type.", "enum": [ "call", "meeting", "slot", "block" ] }, "pageSize": { "type": "integer", "description": "Specifies the number of items to retrieve per page. The maximum value is 100." }, "pageNumber": { "type": "integer", "description": "Specifies the page number to retrieve. Used for traditional pagination." } } } } }, { "type": "function", "function": { "name": "create_event", "description": "Create Event", "parameters": { "title": "CreateEventRequestSchema", "type": "object", "properties": { "data": { "type": "object", "required": [ "type", "attributes" ], "properties": { "type": { "type": "string", "enum": [ "events" ] }, "attributes": { "type": "object", "required": [ "calendarId", "eventType" ], "properties": { "calendarId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "call", "meeting", "slot", "block" ] }, "subject": { "type": "string" }, "description": { "type": "string" }, "startMs": { "type": "integer" }, "endMs": { "type": "integer" }, "startAt": { "type": "string" }, "endAt": { "type": "string" }, "timezone": { "type": "string" }, "isAllDay": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "confirmed", "in-progress", "completed", "cancelled", "archived" ] }, "color": { "type": "string" }, "location": { "type": "object" }, "attendees": { "type": "array", "items": { "type": "object" } }, "sourceType": { "type": "string", "enum": [ "calls", "meetings", "briefs" ] }, "sourceId": { "type": "string" }, "metadata": { "type": "object" } } } } } } } } }, { "type": "function", "function": { "name": "show_event", "description": "Show Event", "parameters": { "type": "object", "properties": {} } } }, { "type": "function", "function": { "name": "update_event", "description": "Update Event", "parameters": { "title": "UpdateEventRequestSchema", "type": "object", "properties": { "data": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "events" ] }, "id": { "type": "string" }, "attributes": { "type": "object", "properties": { "subject": { "type": "string" }, "description": { "type": "string" }, "startMs": { "type": "integer" }, "endMs": { "type": "integer" }, "startAt": { "type": "string" }, "endAt": { "type": "string" }, "timezone": { "type": "string" }, "isAllDay": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "confirmed", "in-progress", "completed", "cancelled", "archived" ] }, "color": { "type": "string" }, "location": { "type": "object" }, "metadata": { "type": "object" } } } } } } } } }, { "type": "function", "function": { "name": "delete_event", "description": "Delete Event", "parameters": { "type": "object", "properties": { "permanentDelete": { "type": "string", "description": "Set to `true` for hard-delete.", "enum": [ "true", "false" ] } } } } } ]