{ "openapi": "3.0.0", "x-mcp": { "enabled": true }, "info": { "version": "3.0.0", "title": "Octave API", "description": "API for Octave workspace management and AI-powered content generation" }, "servers": [ { "url": "https://app.octavehq.com" } ], "security": [ { "ApiKeyAuth": [] } ], "x-typescript-config": { "discriminatorMapping": true, "enumNaming": "PascalCase", "interfaceNaming": "PascalCase" }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "api_key" } }, "schemas": { "EnrichCompanyAgentInput": { "type": "object", "properties": { "companyDomain": { "type": "string", "nullable": true, "description": "Company domain to enrich", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name to enrich", "example": "Example" }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context", "example": { "user": { "oId": "user_123" } } }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } }, "required": [ "agentOId" ] }, "EnrichPersonAgentInput": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to enrich", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to enrich", "example": "John" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to enrich", "example": "Software Engineer" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain of the person to enrich" }, "companyName": { "type": "string", "nullable": true, "description": "Company name of the person to enrich", "example": "Example" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to enrich", "example": "https://www.linkedin.com/in/john-doe/" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context", "example": { "user": { "oId": "user_123" } } }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } }, "required": [ "agentOId" ] }, "GenerateContentAgentInput": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to generate content for", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to generate content for" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to generate content for" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain to generate content for", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name to generate content for" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to generate content for" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context" }, "url": { "type": "string", "nullable": true, "description": "URL to generate content for" }, "customContext": { "type": "object", "nullable": true, "properties": { "playbook": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "product": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "service": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "persona": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "segment": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] } }, "description": "Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning).", "example": { "persona": { "oId": "pe_xxxxxxxxxxxxxxxxxxxxx" }, "segment": { "oId": "sg_xxxxxxxxxxxxxxxxxxxxx" } } }, "outputFormat": { "type": "string", "nullable": true, "enum": [ "JSON", "TEXT", "HTML", "MARKDOWN", null ] }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "experimentOId": { "type": "string", "description": "ExperimentOId is required when running an experiment", "example": "experiment_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } } }, "SequenceAgentInput": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to generate emails for", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to generate emails for" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to generate emails for" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain of the person to generate emails for", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name of the person to generate emails for" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to generate emails for" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "lang": { "type": "string", "nullable": true, "description": "Language of the person to generate emails for" }, "requestId": { "type": "string", "nullable": true }, "outputFormat": { "type": "string", "nullable": true, "enum": [ "text", "html", "markdown", null ], "default": "text", "description": "Output format of the emails to generate" }, "runtimeContext": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional context (facts, research, account data) injected at runtime to personalize the generated sequence. Keys control which email steps receive the context: \"all\" applies to every email, \"1\"-\"4\" apply to a specific step (1-based index). Step-specific context is merged with the \"all\" context.", "example": { "1": "Reference her AWS SCA leadership role in the opening.", "all": "Account research: NICE Ltd expanded their AI partner program from 25 to 200 partners. Sarah leads strategic alliances." } }, "runtimeInstructions": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Behavioral directives that control how the agent writes the sequence \u2014 tone, structure, emphasis, constraints. Keys work the same way as runtimeContext: \"all\" applies to every email, \"1\"-\"4\" apply to a specific step (1-based index). Use runtimeInstructions for writing style directives. Use runtimeContext for factual data.", "example": { "1": "Lead with a specific personal detail \u2014 do not open with a generic intro.", "all": "Keep emails under 150 words. Use a consultative tone, not salesy." } }, "playbookSelectionContext": { "type": "string", "nullable": true, "description": "Playbook selection context of the person to generate emails for" }, "customContext": { "type": "object", "nullable": true, "properties": { "playbook": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "product": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "service": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "persona": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "segment": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] } }, "description": "Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning).", "example": { "persona": { "oId": "pe_xxxxxxxxxxxxxxxxxxxxx" }, "segment": { "oId": "sg_xxxxxxxxxxxxxxxxxxxxx" } } }, "fullSequenceMode": { "type": "boolean" }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "experimentOId": { "type": "string", "description": "ExperimentOId is required when running an experiment", "example": "experiment_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } } }, "QualifyPersonAgentInput": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to qualify", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to qualify" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to qualify" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain of the person to qualify", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name of the person to qualify" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to qualify" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context for qualification" }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } }, "required": [ "agentOId" ] }, "QualifyCompanyAgentInput": { "type": "object", "properties": { "companyDomain": { "type": "string", "nullable": true, "description": "Company domain to qualify", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name to qualify" }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context for qualification" }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } }, "required": [ "agentOId" ] }, "ProspectorAgentInput": { "type": "object", "properties": { "companyDomain": { "type": "string", "description": "Company to find prospects or use as lookalike source", "example": "example.com" }, "limit": { "type": "number", "nullable": true, "description": "Override the Agent's configured limit", "example": 10, "minimum": 1, "maximum": 1000 }, "minimal": { "type": "boolean", "default": true, "description": "Minimize the output. If set to true, `positions`, `internalPictureUrl`, and the nested `company` object will be omitted from the output.", "example": true }, "searchContext": { "type": "object", "properties": { "playbookOId": { "type": "string", "nullable": true }, "personaOIds": { "type": "array", "nullable": true, "items": { "type": "string" } }, "fuzzyTitles": { "type": "array", "nullable": true, "items": { "type": "string" } }, "exactTitles": { "type": "array", "nullable": true, "items": { "type": "string" } }, "excludeTitles": { "type": "array", "nullable": true, "items": { "type": "string" } }, "personCountry": { "type": "object", "nullable": true, "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } }, "personLocation": { "type": "object", "nullable": true, "properties": { "countryCode": { "type": "object", "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } }, "city": { "type": "object", "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } }, "text": { "type": "object", "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } } } } }, "description": "Optional search context to override agent's configured search context. If provided, the two objects will be merged." }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" } }, "required": [ "companyDomain", "agentOId" ] }, "GenericEmailEvent": { "type": "object", "properties": { "eventTimestamp": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Timestamp of the event. Accepts an ISO 8601 string (e.g., \"2024-02-03T10:30:00Z\"), a Unix epoch in milliseconds (>= 1e12), or a Unix epoch in seconds. Must resolve to a date within 50 years past or 5 years future.", "example": "2024-02-03T10:30:00Z" }, "eventType": { "type": "string", "enum": [ "sent", "reply", "opened", "clicked", "bounced", "unsubscribed" ], "description": "Type of email event. Only 'sent' and 'reply' are processed for analytics; others are ingested but not processed." }, "subject": { "type": "string", "description": "Email subject line", "example": "Follow up on our conversation" }, "body": { "type": "object", "properties": { "text": { "type": "string", "description": "Plain text body" }, "html": { "type": "string", "description": "HTML body" } }, "description": "Email body. At least one of text or html must be provided." }, "from": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "sender@company.com" }, "name": { "type": "string", "example": "Sarah Johnson" } }, "required": [ "email" ], "description": "Sender" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "recipient@prospect.com" }, "name": { "type": "string", "example": "John Smith" } }, "required": [ "email" ] }, "minItems": 1, "description": "Recipients (at least one required)" }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "email" ] }, "description": "CC recipients" }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "email" ] }, "description": "BCC recipients" }, "eventId": { "type": "string", "description": "Explicit event ID for deduplication. If not provided, auto-generated from: from_email + subject + timestamp + first_to_email", "example": "deal-001-email-sent-1" }, "conversationId": { "type": "string", "description": "Conversation/thread ID for grouping related emails" }, "campaignId": { "type": "string", "description": "Campaign ID for grouping campaign emails" }, "octaveRequestId": { "type": "string", "description": "Octave request ID for tracking" }, "sourceProviderName": { "type": "string", "description": "Display override for the activity feed. Case-insensitive match against a supported provider name; when set, that provider's logo is shown instead of the generic Octave icon." }, "crmOpportunityId": { "type": "string", "description": "Your system's deal ID. Links this event straight to that opportunity instead of Octave inferring the deal from participants and timing \u2014 which misses when the participant is not on the deal, and mis-fires when two deals share a domain.", "example": "opp_12345" }, "crmAccountId": { "type": "string", "description": "Your system's account/company ID, for account-level linking", "example": "acct_67890" }, "crmAccountDomain": { "type": "string", "description": "Account domain, used when no deal ID is known", "example": "acme.com" }, "customMetadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Arbitrary key-value metadata" } }, "required": [ "eventTimestamp", "eventType", "subject", "body", "from", "to" ] }, "GenericCallEvent": { "type": "object", "properties": { "eventTimestamp": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Timestamp of the event. Accepts an ISO 8601 string (e.g., \"2024-02-03T10:30:00Z\"), a Unix epoch in milliseconds (>= 1e12), or a Unix epoch in seconds. Must resolve to a date within 50 years past or 5 years future.", "example": "2024-02-03T14:00:00Z" }, "eventType": { "type": "string", "enum": [ "transcript", "scheduled", "completed", "missed" ], "description": "Type of call event. Only 'transcript' is processed for analytics; others are ingested but not processed." }, "title": { "type": "string", "description": "Call/meeting title", "example": "Discovery Call - Acme Corp" }, "transcript": { "anyOf": [ { "type": "string", "minLength": 1, "description": "Flat text transcript (will use LLM diarization)" }, { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "object", "properties": { "name": { "type": "string", "example": "Sarah Johnson" }, "email": { "type": "string", "format": "email", "example": "sarah@company.com" }, "role": { "type": "string", "enum": [ "internal", "external" ], "description": "'internal' for your team, 'external' for prospects/customers" } }, "required": [ "name" ] }, "text": { "type": "string", "example": "Hi John, thanks for taking the time today." }, "timestamp": { "type": "string", "description": "Timestamp offset (ISO 8601 or seconds from start)", "example": "00:00:05" } }, "required": [ "speaker", "text" ] }, "minItems": 1, "description": "Structured transcript entries with speaker attribution (recommended \u2014 no LLM needed)" } ], "description": "Transcript content. Either a flat string (LLM diarizes into speaker turns) or a structured array of entries with speaker attribution (recommended, faster and more reliable)." }, "participants": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "sarah@company.com" }, "name": { "type": "string", "example": "Sarah Johnson" }, "role": { "type": "string", "enum": [ "internal", "external" ] } }, "required": [ "name" ] }, "minItems": 1, "description": "Call participants (at least one required)" }, "duration": { "type": "number", "description": "Call duration in seconds", "example": 1800 }, "recordingUrl": { "type": "string", "format": "uri", "description": "URL to the call recording" }, "meetingPlatform": { "type": "string", "description": "Meeting platform (e.g., 'zoom', 'teams', 'meet')", "example": "zoom" }, "eventId": { "type": "string", "description": "Explicit event ID for deduplication. If not provided, auto-generated from: title + timestamp + first_participant + first_100_chars_transcript", "example": "deal-001-call-discovery" }, "conversationId": { "type": "string", "description": "Conversation ID for grouping related calls" }, "sourceProviderName": { "type": "string", "description": "Display override for the activity feed. Case-insensitive match against a supported provider name; when set, that provider's logo is shown instead of the generic Octave icon." }, "crmOpportunityId": { "type": "string", "description": "Your system's deal ID. Links this event straight to that opportunity instead of Octave inferring the deal from participants and timing \u2014 which misses when the participant is not on the deal, and mis-fires when two deals share a domain.", "example": "opp_12345" }, "crmAccountId": { "type": "string", "description": "Your system's account/company ID, for account-level linking", "example": "acct_67890" }, "crmAccountDomain": { "type": "string", "description": "Account domain, used when no deal ID is known", "example": "acme.com" }, "customMetadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Arbitrary key-value metadata" } }, "required": [ "eventTimestamp", "eventType", "title", "transcript", "participants" ] }, "GenericCrmEvent": { "type": "object", "properties": { "eventTimestamp": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Timestamp of the event. Accepts an ISO 8601 string (e.g., \"2024-02-03T10:30:00Z\"), a Unix epoch in milliseconds (>= 1e12), or a Unix epoch in seconds. Must resolve to a date within 50 years past or 5 years future.", "example": "2024-02-03T16:00:00Z" }, "eventType": { "type": "string", "enum": [ "opportunity_created", "deal_won", "deal_lost", "meeting_booked" ], "description": "Type of CRM event" }, "eventId": { "type": "string", "description": "Explicit event ID for deduplication. When omitted it is derived from opportunityId + eventType + the deal's current state, so re-sending a CHANGED deal is treated as a new event rather than a duplicate of the last push." }, "opportunityId": { "type": "string", "description": "External opportunity/deal ID", "example": "opp_12345" }, "opportunityName": { "type": "string", "description": "Name of the opportunity/deal", "example": "Acme Corp - Enterprise Plan" }, "amount": { "anyOf": [ { "type": "number" }, { "type": "string" } ], "description": "Deal amount. Send a string to preserve decimal precision exactly as your system holds it.", "example": "50000.00" }, "currency": { "type": "string", "description": "ISO currency code for amount", "example": "USD" }, "stage": { "type": "string", "description": "Deal stage", "example": "Qualification" }, "stageCategory": { "type": "string", "enum": [ "open", "closed_won", "closed_lost" ], "description": "Normalized stage bucket. Supply this when your stage names do not map cleanly from eventType \u2014 without it the category is inferred from the event type alone, so a deal sitting in late-stage procurement still reads as open.", "example": "open" }, "crmPipelineId": { "type": "string", "description": "Pipeline/record-type ID the deal belongs to" }, "crmPipelineName": { "type": "string", "description": "Human-readable pipeline name", "example": "Sales" }, "accountName": { "type": "string", "description": "Account/company name", "example": "Acme Corp" }, "crmAccountId": { "type": "string", "description": "Your system's account/company ID \u2014 the durable join key for account linking. Matching on name alone cannot separate two deals that share a company name under different domains.", "example": "acct_67890" }, "crmAccountDomain": { "type": "string", "description": "Account domain, used to link events by company", "example": "acme.com" }, "contactEmail": { "type": "string", "format": "email", "description": "Primary contact email", "example": "john@acme.com" }, "contactEmails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Every contact on the deal, not just the primary. Event linking matches on all of them, so sending the full set is the biggest lever on how many emails and calls attach to this opportunity.", "example": [ "john@acme.com", "priya@acme.com" ] }, "ownerName": { "type": "string", "description": "Deal owner's display name" }, "ownerEmail": { "type": "string", "format": "email", "description": "Deal owner's email \u2014 lets Octave match the owner to a teammate", "example": "rep@yourcompany.com" }, "crmOwnerId": { "type": "string", "description": "Your system's owner/user ID, joinable against your own tables" }, "lossReason": { "type": "string", "description": "Verbatim closed-lost reason. Classified into a category on ingest and used for win/loss analysis.", "example": "Went with competitor" }, "mergedOpportunityIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of deals merged INTO this one. Their mirrors are folded into this deal and tombstoned, so a merge does not leave duplicates counting toward pipeline." }, "contactName": { "type": "string", "description": "Primary contact name", "example": "John Smith" }, "closeDate": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Expected close date. Accepts an ISO 8601 string (e.g., \"2024-03-31T00:00:00Z\"), a Unix epoch in milliseconds (>= 1e12), or a Unix epoch in seconds. Must resolve to a date within 50 years past or 5 years future.", "example": "2024-03-31T00:00:00Z" }, "createdDate": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "When the deal was created in your system. Defaults to eventTimestamp.", "example": "2024-02-03T16:00:00Z" }, "crmLastModifiedAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "When the deal last changed in your system. Strongly recommended: it is the state marker that lets a re-sent deal be recognised as a NEW state rather than a duplicate of the previous push, which is what allows amount, stage and close-date edits to land.", "example": "2024-02-03T16:00:00Z" }, "sourceProviderName": { "type": "string", "description": "Display override for the activity feed. Case-insensitive match against a supported provider name; when set, that provider's logo is shown instead of the generic Octave icon." }, "customMetadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Arbitrary key-value metadata" } }, "required": [ "eventTimestamp", "eventType", "opportunityId", "opportunityName" ] }, "GenericSocialEvent": { "type": "object", "properties": { "eventTimestamp": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Timestamp of the event. Accepts an ISO 8601 string (e.g., \"2024-02-03T10:30:00Z\"), a Unix epoch in milliseconds (>= 1e12), or a Unix epoch in seconds. Must resolve to a date within 50 years past or 5 years future.", "example": "2024-02-03T11:00:00Z" }, "eventType": { "type": "string", "enum": [ "connection_sent", "connection_accepted", "message_sent", "message_received" ], "description": "Type of social event (LinkedIn/social outreach). All types are processed for analytics." }, "body": { "type": "object", "properties": { "text": { "type": "string", "description": "Plain text body" }, "html": { "type": "string", "description": "HTML body" } }, "description": "Message body. At least one of text or html must be provided." }, "from": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "sender@company.com" }, "name": { "type": "string", "example": "Sarah Johnson" } }, "required": [ "email" ], "description": "Sender" }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "recipient@prospect.com" }, "name": { "type": "string", "example": "John Smith" } }, "required": [ "email" ] }, "minItems": 1, "description": "Recipients (at least one required)" }, "subject": { "type": "string", "description": "Subject or topic of the message" }, "eventId": { "type": "string", "description": "Explicit event ID for deduplication" }, "conversationId": { "type": "string", "description": "Conversation/thread ID for grouping related messages" }, "campaignId": { "type": "string", "description": "Campaign ID for grouping" }, "messageType": { "type": "string", "description": "Message type (e.g. message, inmail, connection_request)" }, "campaignName": { "type": "string", "description": "Campaign name" }, "octaveRequestId": { "type": "string", "description": "Octave request ID for tracking" }, "sourceProviderName": { "type": "string", "description": "Display override for the activity feed. Case-insensitive match against a supported provider name; when set, that provider's logo is shown instead of the generic Octave icon." }, "crmOpportunityId": { "type": "string", "description": "Your system's deal ID. Links this event straight to that opportunity instead of Octave inferring the deal from participants and timing \u2014 which misses when the participant is not on the deal, and mis-fires when two deals share a domain.", "example": "opp_12345" }, "crmAccountId": { "type": "string", "description": "Your system's account/company ID, for account-level linking", "example": "acct_67890" }, "crmAccountDomain": { "type": "string", "description": "Account domain, used when no deal ID is known", "example": "acme.com" }, "customMetadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Arbitrary key-value metadata" } }, "required": [ "eventTimestamp", "eventType", "body", "from", "to" ] }, "EntityRevisionDiff": { "type": "object", "properties": { "added": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Fields present in the new entity but not the previous one." }, "removed": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Fields present in the previous entity but not the new one." }, "changed": { "type": "object", "additionalProperties": { "type": "object", "properties": { "from": { "nullable": true }, "to": { "nullable": true }, "nested": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Present when the changed field is itself an object: a nested EntityRevisionDiff with the same {added, removed, changed} shape." } } }, "description": "Fields whose value changed. Leaf changes are `{from, to}`; nested object changes carry a `{nested}` sub-diff." } }, "required": [ "added", "removed", "changed" ] }, "Metadata": { "type": "object", "properties": { "usage": { "type": "number", "default": 0, "example": 0, "description": "API usage" }, "requestId": { "type": "string", "example": "requestId", "description": "Request ID" }, "message": { "type": "string", "example": "message", "description": "Message" }, "timestamp": { "type": "string", "example": "2021-01-01T00:00:00.000Z", "description": "Timestamp" } }, "required": [ "requestId", "timestamp" ] }, "ApiKeyData": { "type": "object", "properties": { "name": { "type": "string", "example": "Untitled", "description": "Name of the API key" }, "key": { "type": "string", "example": "key", "description": "API key" }, "product": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "example": "oId", "description": "Product OId" }, "name": { "type": "string", "example": "name", "description": "Product name" } }, "required": [ "oId", "name" ], "description": "Associated product" }, "playbook": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "example": "oId", "description": "Playbook OId" }, "name": { "type": "string", "example": "name", "description": "Playbook name" } }, "required": [ "oId", "name" ], "description": "Associated playbook" }, "template": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "description": "Template OId" }, "name": { "type": "string", "example": "name", "description": "Template name" } }, "required": [ "oId", "name" ], "description": "Associated template" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date", "example": "2021-01-01T00:00:00.000Z" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Update date", "example": "2021-01-01T00:00:00.000Z" } }, "required": [ "name", "key", "createdAt", "updatedAt" ] }, "PersonData": { "type": "object", "properties": { "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona" }, "primaryResponsibilities": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The primary responsibilities of the persona", "example": [ "Responsibility 1", "Responsibility 2" ] }, "painPoints": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The pain points of the persona", "example": [ "Pain Point 1", "Pain Point 2" ] }, "keyConcerns": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The key concerns of the persona", "example": [ "Concern 1", "Concern 2" ] }, "keyObjectives": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The key objectives of the persona", "example": [ "Objective 1", "Objective 2" ] }, "commonJobTitles": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The common job titles of the persona", "example": [ "Job Title 1", "Job Title 2" ] }, "whyTheyMatterToUs": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The reasons why the persona matters to us", "example": [ "Reason 1", "Reason 2" ] }, "whyWeMatterToThem": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The reasons why we matter to this type of persona", "example": [ "Reason 1", "Reason 2" ] }, "buyingRole": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The function this persona typically plays in a purchase decision (e.g. economic buyer, champion, technical evaluator, end user, influencer, blocker), along with their level of sophistication on the problem space (newcomer, experienced, expert).", "example": [ "Economic buyer with budget authority over the GTM stack.", "Experienced operator who has evaluated similar tooling before." ] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "CustomDataFields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomDataFieldItem" } }, "CustomDataFieldItem": { "type": "object", "properties": { "title": { "type": "string" }, "value": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "value" ] }, "Persona": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "Persona OId", "example": "p_1234" }, "name": { "type": "string", "nullable": true, "description": "Persona name", "example": "VP of Sales" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "nullable": true, "description": "Persona description" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether persona is unrecognized", "example": false }, "rejected": { "type": "boolean", "nullable": true, "description": "Whether persona is rejected", "example": false }, "active": { "type": "boolean", "default": true, "description": "Whether the persona is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/PersonData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the persona", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the persona", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the persona", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the persona belongs to", "example": "wa_1234" } }, "description": "Workspace data" } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] }, "PersonaData": { "type": "object", "properties": { "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona" }, "primaryResponsibilities": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The primary responsibilities of the persona", "example": [ "Responsibility 1", "Responsibility 2" ] }, "painPoints": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The pain points of the persona", "example": [ "Pain Point 1", "Pain Point 2" ] }, "keyConcerns": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The key concerns of the persona", "example": [ "Concern 1", "Concern 2" ] }, "keyObjectives": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The key objectives of the persona", "example": [ "Objective 1", "Objective 2" ] }, "commonJobTitles": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The common job titles of the persona", "example": [ "Job Title 1", "Job Title 2" ] }, "whyTheyMatterToUs": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The reasons why the persona matters to us", "example": [ "Reason 1", "Reason 2" ] }, "whyWeMatterToThem": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The reasons why we matter to this type of persona", "example": [ "Reason 1", "Reason 2" ] }, "buyingRole": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The function this persona typically plays in a purchase decision (e.g. economic buyer, champion, technical evaluator, end user, influencer, blocker), along with their level of sophistication on the problem space (newcomer, experienced, expert).", "example": [ "Economic buyer with budget authority over the GTM stack.", "Experienced operator who has evaluated similar tooling before." ] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "LinkingStrategy": { "oneOf": [ { "$ref": "#/components/schemas/LinkingStrategyAll" }, { "$ref": "#/components/schemas/LinkingStrategySpecific" } ], "discriminator": { "propertyName": "mode", "mapping": { "ALL": "#/components/schemas/LinkingStrategyAll", "SPECIFIC": "#/components/schemas/LinkingStrategySpecific" } }, "default": { "mode": "ALL" }, "description": "Strategy for linking this persona to offerings (products/services)" }, "LinkingStrategyAll": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "ALL" ], "description": "Link to all active offerings in the workspace (products, services, and solutions)", "example": "ALL" } }, "required": [ "mode" ] }, "LinkingStrategySpecific": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "SPECIFIC" ], "description": "Link to specific offerings by their IDs (products, services, and solutions)", "example": "SPECIFIC" }, "offeringOIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Array of offering IDs to link to (supports product, service, and solution oIds)", "example": [ "px_123", "sc_456", "sv_789" ] } }, "required": [ "mode", "offeringOIds" ] }, "PersonaGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the persona - if provided, will be used as the entity name", "example": "Enterprise Sales Leader" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the persona from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of persona generation requests - each object generates one persona", "example": [ { "name": "Enterprise Sales Leader", "sources": [ { "type": "TEXT", "value": "VP of Sales professionals who manage enterprise deals and drive revenue growth" } ] }, { "sources": [ { "type": "URL", "value": "https://example.com/target-customer-profile" } ] } ] }, "EnrichCompanyAgentData": { "type": "object", "nullable": true, "properties": { "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "founded": { "type": "number", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "nullable": true }, "locality": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "streetAddress": { "type": "string", "nullable": true } } }, "employeeCount": { "type": "number", "nullable": true }, "followerCount": { "type": "number", "nullable": true }, "type": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "specialties": { "type": "array", "nullable": true, "items": { "type": "string" } }, "industry": { "type": "string", "nullable": true }, "crunchBaseFunding": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "fundingRoundCount": { "type": "number", "nullable": true }, "roundDate": { "type": "string", "nullable": true, "format": "date-time" }, "roundName": { "type": "string", "nullable": true }, "investorNames": { "type": "array", "nullable": true, "items": { "type": "string" } }, "investorCount": { "type": "number", "nullable": true }, "roundAmount": { "type": "number", "nullable": true }, "roundCurrency": { "type": "string", "nullable": true } } } } }, "description": "Company details" }, "product": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the product", "example": "Product Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the product", "example": "Product Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the product", "example": "https://www.product.com" }, "data": { "$ref": "#/components/schemas/ProductData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "required": [ "data" ], "description": "Product details" }, "service": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the service", "example": "Service Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the service", "example": "Service Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the service", "example": "https://www.service.com" }, "data": { "$ref": "#/components/schemas/ServiceData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "required": [ "data" ], "description": "Service details" }, "solution": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/SolutionPersistedData" }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "required": [ "data" ], "description": "Solution details" }, "research": { "type": "object", "nullable": true, "properties": { "summary": { "type": "array", "items": { "type": "string" } }, "businessDescription": { "type": "array", "items": { "type": "string" } }, "businessCharacteristics": { "type": "array", "items": { "type": "string" } }, "businessEnvironment": { "type": "array", "items": { "type": "string" } } }, "required": [ "summary", "businessDescription", "businessCharacteristics", "businessEnvironment" ], "description": "Research details" }, "valueProps": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "evidence": { "type": "array", "nullable": true, "items": { "type": "string" } } } }, "description": "Value props details" }, "references": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "default": "" }, "oId": { "type": "string", "nullable": true }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true }, "howTheyUseUs": { "type": "string", "nullable": true, "default": "" }, "impactTheySaw": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [] } } }, "description": "References details" }, "useCase": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the use case", "example": "Use Case Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the use case", "example": "Use Case Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the use case", "example": "https://www.use-case.com" }, "data": { "$ref": "#/components/schemas/UseCaseData" }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "description": "Use case details" }, "playbook": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": [ "LEGACY", "SECTOR", "SOLUTION", "MILESTONE", "PRACTITIONER", "COMPETITIVE", "ACCOUNT", "CUSTOM", null ] }, "keyInsight": { "type": "array", "items": { "type": "string" } }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "description": "Playbook details" }, "annotations": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string" }, "meta": { "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true } }, "required": [ "type", "title" ] } }, "metadata": { "nullable": true } } }, "customTask": { "type": "object", "nullable": true, "properties": { "content": { "nullable": true, "description": "Structured JSON output from the custom task" }, "error": { "type": "string", "nullable": true, "description": "Error message if the custom task failed" } } } } }, "ProductData": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ], "default": "PRODUCT" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the product" }, "summary": { "type": "string", "nullable": true }, "distinctCapabilities": { "type": "array", "items": { "type": "string" }, "default": [], "description": "What the product does at the functional level, and what it enables customers to accomplish. Outcome-oriented, not mechanism-oriented (mechanisms live in keyFunctionality).", "example": [ "Capability 1", "Capability 2" ] }, "keyFunctionality": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The specific, named, often branded components of the product worth highlighting. Concrete and tangible; these help frame the 'how' behind the capabilities.", "example": [ "Functionality 1", "Functionality 2" ] }, "differentiatedValue": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The differentiated value of the product", "example": [ "Differentiated Value 1", "Differentiated Value 2" ] }, "statusQuo": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The status quo of the product", "example": [ "Status Quo 1", "Status Quo 2" ] }, "challengesAddressed": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The challenges addressed by the offering", "example": [ "Challenge 1", "Challenge 2" ] }, "customerBenefits": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The customer benefits of the offering", "example": [ "Benefit 1", "Benefit 2" ] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "ServiceData": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ], "default": "SERVICE" }, "summary": { "type": "string", "nullable": true }, "deliverables": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Key deliverables of the service", "example": [ "Deliverable 1", "Deliverable 2" ] }, "competencies": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Key competencies required for the service", "example": [ "Competency 1", "Competency 2" ] }, "comparativeAdvantage": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The comparative advantage of the service", "example": [ "Advantage 1", "Advantage 2" ] }, "likelyAlternative": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The likely alternative to the service", "example": [ "Alternative 1", "Alternative 2" ] }, "challengesAddressed": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The challenges addressed by the offering", "example": [ "Challenge 1", "Challenge 2" ] }, "customerBenefits": { "type": "array", "items": { "type": "string" }, "default": [], "description": "The customer benefits of the offering", "example": [ "Benefit 1", "Benefit 2" ] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "SolutionPersistedData": { "type": "object", "properties": { "internalName": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "distinctCapabilities": { "type": "array", "items": { "type": "string" }, "default": [] }, "keyComponents": { "type": "array", "items": { "type": "string" }, "default": [] }, "customerBenefits": { "type": "array", "items": { "type": "string" }, "default": [] }, "challengesAddressed": { "type": "array", "items": { "type": "string" }, "default": [] }, "statusQuo": { "type": "array", "items": { "type": "string" }, "default": [] }, "differentiatedValue": { "type": "array", "items": { "type": "string" }, "default": [] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } }, "type": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ], "default": "SOLUTION" } } }, "UseCaseData": { "type": "object", "nullable": true, "properties": { "summary": { "type": "string", "nullable": true, "description": "Summary" }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" }, "businessDrivers": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Business Drivers" }, "strategicImpact": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "The strategic, business-level benefit realized when this use case is solved well: quantifiable impact on revenue, cost, risk, and/or efficiency, and the broader value to the company." }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "EnrichPersonAgentData": { "type": "object", "nullable": true, "properties": { "product": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the product", "example": "Product Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the product", "example": "Product Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the product", "example": "https://www.product.com" }, "data": { "$ref": "#/components/schemas/ProductData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "required": [ "data" ] }, "service": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the service", "example": "Service Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the service", "example": "Service Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the service", "example": "https://www.service.com" }, "data": { "$ref": "#/components/schemas/ServiceData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "required": [ "data" ] }, "solution": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/SolutionPersistedData" }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "required": [ "data" ] }, "persona": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "nullable": true, "description": "The description of the persona" }, "data": { "$ref": "#/components/schemas/PersonaData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "required": [ "data" ] }, "useCase": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the use case", "example": "Use Case Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the use case", "example": "Use Case Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the use case", "example": "https://www.use-case.com" }, "data": { "$ref": "#/components/schemas/UseCaseData" }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } } }, "playbook": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": [ "LEGACY", "SECTOR", "SOLUTION", "MILESTONE", "PRACTITIONER", "COMPETITIVE", "ACCOUNT", "CUSTOM", null ] }, "keyInsight": { "type": "array", "items": { "type": "string" } }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true } } }, "references": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "name": { "type": "string", "default": "" }, "oId": { "type": "string", "nullable": true }, "matchConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "matchAnalysis": { "type": "string", "nullable": true }, "howTheyUseUs": { "type": "string", "nullable": true, "default": "" }, "impactTheySaw": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [] } } } }, "valueProps": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "evidence": { "type": "array", "nullable": true, "items": { "type": "string" } } } } }, "research": { "type": "object", "nullable": true, "properties": { "currentPosition": { "type": "array", "items": { "type": "string" } }, "previousPositions": { "type": "array", "items": { "type": "string" } }, "keyExpertise": { "type": "array", "items": { "type": "string" } }, "careerArc": { "type": "array", "items": { "type": "string" } }, "notableExperience": { "type": "array", "items": { "type": "string" } }, "keyFindings": { "type": "array", "nullable": true, "items": { "type": "string" } } }, "required": [ "currentPosition", "previousPositions", "keyExpertise", "careerArc", "notableExperience" ] }, "companyResearch": { "type": "array", "nullable": true, "items": { "type": "object", "nullable": true, "properties": { "summary": { "type": "array", "items": { "type": "string" } }, "businessDescription": { "type": "array", "items": { "type": "string" } }, "businessCharacteristics": { "type": "array", "items": { "type": "string" } }, "businessEnvironment": { "type": "array", "items": { "type": "string" } } }, "required": [ "summary", "businessDescription", "businessCharacteristics", "businessEnvironment" ] } }, "profile": { "type": "object", "nullable": true, "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "profileUrl": { "type": "string", "nullable": true }, "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "founded": { "type": "number", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "nullable": true }, "locality": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "streetAddress": { "type": "string", "nullable": true } } }, "employeeCount": { "type": "number", "nullable": true }, "followerCount": { "type": "number", "nullable": true }, "type": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "specialties": { "type": "array", "nullable": true, "items": { "type": "string" } }, "industry": { "type": "string", "nullable": true }, "crunchBaseFunding": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "fundingRoundCount": { "type": "number", "nullable": true }, "roundDate": { "type": "string", "nullable": true, "format": "date-time" }, "roundName": { "type": "string", "nullable": true }, "investorNames": { "type": "array", "nullable": true, "items": { "type": "string" } }, "investorCount": { "type": "number", "nullable": true }, "roundAmount": { "type": "number", "nullable": true }, "roundCurrency": { "type": "string", "nullable": true } } } } } }, "companyName": { "type": "string", "nullable": true }, "companyDomain": { "type": "string", "nullable": true }, "companyFoundedYear": { "type": "number", "nullable": true }, "companyEmployeeCount": { "type": "number", "nullable": true }, "companyDescription": { "type": "string", "nullable": true }, "headline": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "internalPictureUrl": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "currentJobFunction": { "type": "string", "nullable": true }, "currentSeniority": { "type": "string", "nullable": true }, "followers": { "type": "number", "nullable": true }, "allPositionsCount": { "type": "number", "nullable": true }, "currentPositionsCount": { "type": "number", "nullable": true }, "positions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "companyName": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "is_current": { "type": "boolean", "default": false }, "startDate": { "type": "string", "nullable": true, "format": "date-time" }, "endDate": { "type": "string", "nullable": true, "format": "date-time" }, "seniority": { "type": "string", "nullable": true }, "jobFunction": { "type": "string", "nullable": true }, "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "founded": { "type": "number", "nullable": true }, "employeeCount": { "type": "number", "nullable": true }, "description": { "type": "string", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "nullable": true }, "locality": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "streetAddress": { "type": "string", "nullable": true } } }, "slug": { "type": "string", "nullable": true } } } } } } } }, "jobFunction": { "type": "string", "nullable": true }, "seniority": { "type": "string", "nullable": true }, "annotations": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string" }, "meta": { "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true } }, "required": [ "type", "title" ] } }, "metadata": { "nullable": true } } }, "customTask": { "type": "object", "nullable": true, "properties": { "content": { "nullable": true, "description": "Structured JSON output from the custom task" }, "error": { "type": "string", "nullable": true, "description": "Error message if the custom task failed" } } } } }, "GeneratedContentData": { "type": "object", "nullable": true, "properties": { "content": { "type": "string", "nullable": true }, "jsonContent": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "product": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "service": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "solution": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "playbook": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "persona": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "useCases": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "referenceCustomers": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "proofPoints": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "competitors": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "alternatives": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "buyingTriggers": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "coreFeatures": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "objections": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "valueProps": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "evidence": { "type": "array", "nullable": true, "items": { "type": "string" } } } } }, "annotations": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string" }, "meta": { "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true } }, "required": [ "type", "title" ] } }, "metadata": { "nullable": true } } } } }, "LibraryEntitySlot": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "matchConfidence": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", null ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "required": [ "oId", "name" ] }, "EmailAgentData": { "type": "object", "nullable": true, "properties": { "emails": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "email": { "type": "string" }, "subject": { "type": "string" }, "coreValueProp": { "type": "string", "nullable": true, "default": "" }, "sections": { "type": "object", "nullable": true, "properties": { "greeting": { "type": "string", "nullable": true, "default": "" }, "opening": { "type": "string", "nullable": true, "default": "" }, "body": { "type": "string", "nullable": true, "default": "" }, "closing": { "type": "string", "nullable": true, "default": "" }, "cta": { "type": "string", "nullable": true, "default": "" }, "ps": { "type": "string", "nullable": true, "default": "" }, "signature": { "type": "string", "nullable": true, "default": "" } } }, "metadata": { "type": "object", "nullable": true, "properties": { "openerPattern": { "type": "string" }, "hookTopic": { "type": "string" }, "ctaVerb": { "type": "string" }, "valuePropsUsed": { "type": "array", "items": { "type": "string" } }, "referencesUsed": { "type": "array", "items": { "type": "string" } } }, "required": [ "openerPattern", "hookTopic", "ctaVerb", "valuePropsUsed", "referencesUsed" ] } }, "required": [ "email", "subject" ] } }, "product": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "service": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "solution": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "playbook": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "persona": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "useCases": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "referenceCustomers": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "outputType": { "type": "string", "nullable": true, "enum": [ "SCOPED_PLAYBOOK", "BEST_FIT_PLAYBOOK", "RESEARCH_BASED", "ALL", null ] }, "annotations": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string" }, "meta": { "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true } }, "required": [ "type", "title" ] } }, "metadata": { "nullable": true } } } } }, "PlaybookData": { "type": "object", "properties": { "explanation": { "type": "string", "nullable": true }, "attributes": { "type": "object", "nullable": true, "additionalProperties": { "type": "array", "items": { "type": "string" } }, "default": {} }, "keyInsight": { "type": "array", "items": { "type": "string" }, "default": [] }, "exampleDomains": { "type": "array", "items": { "type": "string" }, "default": [] }, "exampleDescription": { "type": "string", "nullable": true, "default": "" }, "approachAngle": { "type": "array", "nullable": true, "items": { "type": "string" } }, "strategicNarrative": { "type": "array", "nullable": true, "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "methodology": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "CVI_WHY_CHANGE" ] }, "data": { "type": "object", "properties": { "coreNarrative": { "type": "array", "items": { "type": "string" } }, "stages": { "type": "object", "properties": { "A1": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] }, "A2": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] }, "A3": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] }, "A4": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] }, "A5": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] } }, "required": [ "A1", "A2", "A3", "A4", "A5" ] }, "generatedAt": { "type": "string" } }, "required": [ "coreNarrative", "stages", "generatedAt" ] } }, "required": [ "type", "data" ] }, { "type": "object", "properties": { "coreNarrative": { "type": "array", "items": { "type": "string" } }, "stages": { "type": "object", "properties": { "A1": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] }, "A2": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] }, "A3": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] }, "A4": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] }, "A5": { "type": "object", "properties": { "overview": { "type": "array", "items": { "type": "string" } }, "whatToKnow": { "type": "array", "items": { "type": "string" } }, "whatToDo": { "type": "array", "items": { "type": "string" } }, "whatToSay": { "type": "array", "items": { "type": "string" } } }, "required": [ "overview", "whatToKnow", "whatToDo", "whatToSay" ] } }, "required": [ "A1", "A2", "A3", "A4", "A5" ] }, "generatedAt": { "type": "string" } }, "required": [ "coreNarrative", "stages", "generatedAt" ] } ] } } }, "PlaybookProduct": { "type": "object", "nullable": true, "properties": { "type": { "type": "string", "nullable": true, "enum": [ "PRODUCT", "SERVICE", "SOLUTION", null ], "description": "Offering type" }, "oId": { "type": "string", "nullable": true, "description": "Product OId" }, "name": { "type": "string", "nullable": true, "description": "Product name" }, "data": { "allOf": [ { "$ref": "#/components/schemas/ProductData" }, { "nullable": true } ] }, "description": { "type": "string", "nullable": true, "description": "Product description" } } }, "PlaybookService": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true, "description": "Service OId" }, "name": { "type": "string", "nullable": true, "description": "Service name" }, "data": { "nullable": true }, "description": { "type": "string", "nullable": true, "description": "Service description" } } }, "PlaybookPersona": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "hypotheses": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Hypothesis" } }, "data": { "allOf": [ { "$ref": "#/components/schemas/PersonaData" }, { "nullable": true } ] } } }, "Hypothesis": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "details": { "type": "string" }, "persona": { "$ref": "#/components/schemas/NameAndOId" }, "playbook": { "$ref": "#/components/schemas/NameAndOId" }, "user": { "$ref": "#/components/schemas/NameAndOId" } }, "required": [ "oId", "createdAt", "name", "details", "persona", "playbook", "user" ] }, "NameAndOId": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true } } }, "PlaybookUseCase": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/UseCaseData" } } }, "PlaybookReference": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/ReferenceData" }, "description": { "type": "string", "nullable": true } } }, "ReferenceData": { "type": "object", "nullable": true, "properties": { "businessModel": { "type": "array", "nullable": true, "items": { "type": "string" } }, "theirChallenge": { "type": "array", "nullable": true, "items": { "type": "string" } }, "howTheyUseUs": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whyTheyChoseUs": { "type": "array", "nullable": true, "items": { "type": "string" } }, "impactTheySaw": { "type": "array", "nullable": true, "items": { "type": "string" } }, "stakeholdersInvolved": { "type": "array", "nullable": true, "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "additionalContextSources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "GOOGLE_DRIVE_FILE_ID", "GENERATIVE_NAME", "OID", "COMPANY_NAME", "FIELDWISE_DOCUMENT_ID", "RAG_DOCUMENT_ID", "RESOURCE", "REPORT", "REPORT_SECTION", "EVENT_OID_FINDINGS", "FINDING_OIDS" ] }, "value": { "type": "string" }, "name": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "useNameIfUrlFails": { "type": "boolean", "nullable": true } }, "required": [ "type", "value" ] }, "description": "Additional context sources for the playbook. URL and TEXT source types are supported.", "example": [ { "type": "URL", "value": "https://example.com/market-research" }, { "type": "TEXT", "value": "Additional market insights about the target segment." } ] }, "UseCaseGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the use case - if provided, will be used as the entity name", "example": "Automated Lead Scoring" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the use case from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of use case generation requests - each object generates one use case", "example": [ { "name": "Automated Lead Scoring", "sources": [ { "type": "TEXT", "value": "Automated lead scoring and qualification process for sales teams" } ] }, { "sources": [ { "type": "URL", "value": "https://example.com/customer-success-story" } ] } ] }, "ReferenceGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the reference - if provided, will be used as the entity name", "example": "Large filesharing service" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the reference from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of reference generation requests - each object generates one reference", "example": [ { "name": "Large filesharing service", "sources": [ { "type": "TEXT", "value": "Leading cloud storage company with 500+ million users" } ] }, { "sources": [ { "type": "URL", "value": "https://example.com/case-study" } ] } ] }, "OfferingListItem": { "oneOf": [ { "allOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PRODUCT" ] } }, "required": [ "type" ] } ] }, { "allOf": [ { "$ref": "#/components/schemas/Service" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SERVICE" ] } }, "required": [ "type" ] } ] }, { "allOf": [ { "$ref": "#/components/schemas/Solution" }, { "type": "object", "properties": { "locked": { "type": "boolean" }, "lockedBy": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "picture": { "type": "string" } }, "required": [ "oId" ] }, "type": { "type": "string", "enum": [ "SOLUTION" ] } }, "required": [ "locked", "type" ] } ] } ] }, "Product": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the product", "example": "p_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the product was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the product was updated", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the product was archived", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the product was deleted", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the product", "example": "Product Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the product", "example": "Product Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the product", "example": "Product Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the product", "example": "https://www.product.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the product is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ProductData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the product", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the product", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the product", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the product belongs to", "example": "wa_1234" } } } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] }, "Service": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the service", "example": "p_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the service was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the service was updated", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the service was archived", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the service was deleted", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the service", "example": "Service Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the service", "example": "Service Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the service", "example": "Service Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the service", "example": "https://www.service.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the service is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ServiceData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the service", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the service", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the service", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the service belongs to", "example": "wa_1234" } } } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] }, "Solution": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the solution", "example": "sv_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the solution was created" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "primaryUrl": { "type": "string", "nullable": true, "description": "Primary website URL for the solution, when available from sources" }, "active": { "type": "boolean", "default": true }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "data": { "$ref": "#/components/schemas/SolutionPersistedData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true } } }, "linkedProducts": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true }, "offeringType": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ] } }, "required": [ "oId", "offeringType" ] }, "default": [] }, "linkedUseCases": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "default": [] }, "linkedPersonas": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "default": [] }, "linkedSegments": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "default": [] } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] }, "ProductGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the product - if provided, will be used as the entity name", "example": "AI-Powered Sales Platform" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the product from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of product generation requests - each object generates one product", "example": [ { "name": "AI-Powered Sales Platform", "sources": [ { "type": "URL", "value": "https://octavehq.com" } ] }, { "sources": [ { "type": "TEXT", "value": "Enterprise CRM solution with advanced analytics and automation features" } ] } ] }, "ServiceGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the service - if provided, will be used as the entity name", "example": "Managed Analytics Onboarding" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the service from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of service generation requests - each object generates one service", "example": [ { "name": "Managed Analytics Onboarding", "sources": [ { "type": "URL", "value": "https://www.example.com/services/onboarding" } ] }, { "sources": [ { "type": "TEXT", "value": "6-week onboarding engagement that configures dashboards and trains customer teams" } ] } ] }, "GeneratedSolutionOutput": { "allOf": [ { "$ref": "#/components/schemas/SolutionData" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ], "default": "SOLUTION" } } } ] }, "SolutionData": { "type": "object", "properties": { "name": { "type": "string" }, "internalName": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "distinctCapabilities": { "type": "array", "items": { "type": "string" }, "default": [] }, "keyComponents": { "type": "array", "items": { "type": "string" }, "default": [] }, "customerBenefits": { "type": "array", "items": { "type": "string" }, "default": [] }, "challengesAddressed": { "type": "array", "items": { "type": "string" }, "default": [] }, "statusQuo": { "type": "array", "items": { "type": "string" }, "default": [] }, "differentiatedValue": { "type": "array", "items": { "type": "string" }, "default": [] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "name" ] }, "SolutionLibraryLinksChange": { "type": "object", "properties": { "add": { "type": "object", "properties": { "offeringOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "useCaseOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "personaOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "segmentOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "referenceOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "collateralOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "competitorOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "alternativeOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "buyingTriggerOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "objectionOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "proofPointOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "genericTextEntityOIds": { "type": "array", "items": { "type": "string" }, "default": [] } }, "description": "Library entity OIds to link to this solution" }, "remove": { "type": "object", "properties": { "offeringOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "useCaseOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "personaOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "segmentOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "referenceOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "collateralOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "competitorOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "alternativeOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "buyingTriggerOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "objectionOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "proofPointOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "genericTextEntityOIds": { "type": "array", "items": { "type": "string" }, "default": [] } }, "description": "Library entity OIds to unlink from this solution" } }, "description": "Add or remove library entity links. Omit to leave existing links unchanged." }, "WorkspaceBuilderData": { "type": "object", "nullable": true, "properties": { "apiKey": { "type": "string", "nullable": true, "description": "API Key for the newly created Workspace" }, "mcpUrl": { "type": "string", "nullable": true, "description": "MCP server URL (with encoded workspace context) for the Workspace. Use together with the API key to connect MCP clients without copying values from the dashboard." }, "offering": { "anyOf": [ { "$ref": "#/components/schemas/Product" }, { "$ref": "#/components/schemas/Service" }, { "nullable": true } ] }, "personas": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the persona", "example": "p_1234" }, "name": { "type": "string", "nullable": true, "description": "The name of the persona", "example": "VP of Sales" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "nullable": true, "description": "The description of the persona" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the persona was created", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was archived", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was updated", "example": "2021-01-01" }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the persona is unrecognized", "example": false }, "rejected": { "type": "boolean", "nullable": true, "description": "Whether the persona is rejected", "example": false }, "active": { "type": "boolean", "default": true, "description": "Whether the persona is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/PersonaData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the persona", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the persona", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the persona", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the persona belongs to", "example": "wa_1234" } } } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } }, "useCases": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the use case", "example": "uc_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the use case was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was archived", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The name of the use case", "example": "Use Case Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the use case", "example": "Use Case Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the use case", "example": "Use Case Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the use case", "example": "https://www.use-case.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the use case is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/UseCaseData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the use case", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the use case", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" } }, "required": [ "oId", "createdAt", "user", "workspace" ] } }, "segments": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "strategicFit": { "type": "array", "items": { "type": "string" }, "default": [] }, "firmographics": { "type": "object", "properties": { "industry": { "type": "array", "items": { "type": "string" }, "default": [] }, "businessModel": { "type": "array", "items": { "type": "string" }, "default": [] }, "geography": { "type": "array", "items": { "type": "string" }, "default": [] }, "revenue": { "type": "array", "items": { "type": "string" }, "default": [] }, "employees": { "type": "array", "items": { "type": "string" }, "default": [] } }, "default": { "industry": [], "businessModel": [], "geography": [], "revenue": [], "employees": [] }, "additionalProperties": { "nullable": true } }, "operatingCharacteristics": { "type": "array", "items": { "type": "string" }, "default": [] }, "strategicPriorities": { "type": "array", "items": { "type": "string" }, "default": [] }, "marketPressures": { "type": "array", "items": { "type": "string" }, "default": [] }, "buyingDynamics": { "type": "array", "items": { "type": "string" }, "default": [] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the segment", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the segment", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "unrecognized": { "type": "boolean" }, "rejected": { "type": "boolean" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "tagGroupOId": { "type": "string" }, "tagGroupName": { "type": "string" }, "tagOId": { "type": "string" }, "tagName": { "type": "string" } }, "required": [ "tagGroupOId", "tagGroupName", "tagOId", "tagName" ] } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName", "unrecognized", "rejected" ] } }, "references": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the reference", "example": "r_1234" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the reference", "example": "Large filesharing service" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the reference", "example": "Dropbox" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the reference was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was archived", "example": "2021-01-01" }, "description": { "type": "string", "nullable": true, "description": "The description of the reference", "example": "Description of the reference" }, "active": { "type": "boolean", "default": true, "description": "Whether the reference is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ReferenceData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the reference", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the reference", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace", "example": "w_1234" } } }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the reference is unrecognized", "example": false } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "isDefault": { "type": "boolean", "nullable": true }, "isOnboarded": { "type": "boolean" }, "visibility": { "type": "string", "nullable": true, "enum": [ "public", "private", null ] }, "description": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "fiscalYearStartMonth": { "type": "integer", "minimum": 1, "maximum": 12, "default": 1 }, "timezone": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdBy": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "organization": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true } } } }, "required": [ "oId", "name", "isOnboarded" ] }, "workspaceCompany": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "data": { "type": "object", "nullable": true, "properties": { "whatWeDo": { "type": "string", "nullable": true }, "whyWeExist": { "type": "array", "items": { "type": "string" } }, "howWePositionOurselves": { "type": "array", "items": { "type": "string" } }, "whoWeHelp": { "type": "array", "items": { "type": "string" } }, "whatMakesUsUnique": { "type": "array", "items": { "type": "string" } }, "businessModel": { "type": "array", "items": { "type": "string" } }, "marketDynamics": { "type": "array", "items": { "type": "string" } }, "whyCustomersBuy": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whyCustomersCare": { "type": "array", "nullable": true, "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "customMarketFields": { "$ref": "#/components/schemas/CustomDataFields" } }, "required": [ "whyWeExist", "howWePositionOurselves", "whoWeHelp", "whatMakesUsUnique", "businessModel", "marketDynamics" ] }, "description": { "type": "string", "nullable": true }, "name": { "type": "string" }, "url": { "type": "string" }, "internalName": { "type": "string", "nullable": true }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "url" ] }, "playbookSuggestions": { "type": "object", "nullable": true, "properties": { "solution": { "type": "array", "nullable": true, "items": { "type": "string" } }, "sector": { "type": "array", "nullable": true, "items": { "type": "string" } }, "practitioner": { "type": "array", "nullable": true, "items": { "type": "string" } }, "milestone": { "type": "array", "nullable": true, "items": { "type": "string" } } } } }, "required": [ "workspace", "workspaceCompany" ] }, "QualifyPersonAgentData": { "type": "object", "nullable": true, "properties": { "person": { "type": "object", "nullable": true, "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "profileUrl": { "type": "string", "nullable": true }, "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "founded": { "type": "number", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "nullable": true }, "locality": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "streetAddress": { "type": "string", "nullable": true } } }, "employeeCount": { "type": "number", "nullable": true }, "followerCount": { "type": "number", "nullable": true }, "type": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "specialties": { "type": "array", "nullable": true, "items": { "type": "string" } }, "industry": { "type": "string", "nullable": true }, "crunchBaseFunding": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "fundingRoundCount": { "type": "number", "nullable": true }, "roundDate": { "type": "string", "nullable": true, "format": "date-time" }, "roundName": { "type": "string", "nullable": true }, "investorNames": { "type": "array", "nullable": true, "items": { "type": "string" } }, "investorCount": { "type": "number", "nullable": true }, "roundAmount": { "type": "number", "nullable": true }, "roundCurrency": { "type": "string", "nullable": true } } } } } }, "companyName": { "type": "string", "nullable": true }, "companyDomain": { "type": "string", "nullable": true }, "companyFoundedYear": { "type": "number", "nullable": true }, "companyEmployeeCount": { "type": "number", "nullable": true }, "companyDescription": { "type": "string", "nullable": true }, "headline": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "internalPictureUrl": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "currentJobFunction": { "type": "string", "nullable": true }, "currentSeniority": { "type": "string", "nullable": true }, "followers": { "type": "number", "nullable": true }, "allPositionsCount": { "type": "number", "nullable": true }, "currentPositionsCount": { "type": "number", "nullable": true }, "positions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "companyName": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "is_current": { "type": "boolean", "default": false }, "startDate": { "type": "string", "nullable": true, "format": "date-time" }, "endDate": { "type": "string", "nullable": true, "format": "date-time" }, "seniority": { "type": "string", "nullable": true }, "jobFunction": { "type": "string", "nullable": true }, "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "founded": { "type": "number", "nullable": true }, "employeeCount": { "type": "number", "nullable": true }, "description": { "type": "string", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "nullable": true }, "locality": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "streetAddress": { "type": "string", "nullable": true } } }, "slug": { "type": "string", "nullable": true } } } } } } } }, "seniority": { "type": "string", "nullable": true }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true }, "product": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "service": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "solution": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "persona": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "segment": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "playbook": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "annotations": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string" }, "meta": { "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true } }, "required": [ "type", "title" ] } }, "metadata": { "nullable": true } } }, "customTask": { "type": "object", "nullable": true, "properties": { "content": { "nullable": true, "description": "Structured JSON output from the custom task" }, "error": { "type": "string", "nullable": true, "description": "Error message if the custom task failed" } } }, "disqualifierSummary": { "type": "object", "nullable": true, "properties": { "triggered": { "type": "boolean" }, "firstQuestion": { "type": "string", "nullable": true }, "firstRationale": { "type": "string", "nullable": true }, "totalCount": { "type": "number" } }, "required": [ "triggered", "firstQuestion", "firstRationale", "totalCount" ] } }, "required": [ "score", "rationale", "product", "service", "solution", "persona", "segment", "playbook" ] }, "QualifyCompanyAgentData": { "type": "object", "nullable": true, "properties": { "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "founded": { "type": "number", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "nullable": true }, "locality": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "streetAddress": { "type": "string", "nullable": true } } }, "employeeCount": { "type": "number", "nullable": true }, "followerCount": { "type": "number", "nullable": true }, "type": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "specialties": { "type": "array", "nullable": true, "items": { "type": "string" } }, "industry": { "type": "string", "nullable": true }, "crunchBaseFunding": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "fundingRoundCount": { "type": "number", "nullable": true }, "roundDate": { "type": "string", "nullable": true, "format": "date-time" }, "roundName": { "type": "string", "nullable": true }, "investorNames": { "type": "array", "nullable": true, "items": { "type": "string" } }, "investorCount": { "type": "number", "nullable": true }, "roundAmount": { "type": "number", "nullable": true }, "roundCurrency": { "type": "string", "nullable": true } } } } } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true }, "product": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "service": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "solution": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "segment": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "playbook": { "type": "object", "nullable": true, "properties": { "message": { "type": "string", "nullable": true }, "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "qualification": { "type": "object", "nullable": true, "properties": { "answers": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "answer": { "type": "string", "description": "The answer to the question" }, "rationale": { "type": "string", "description": "The rationale for the answer" }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The confidence in the answer" }, "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "weight": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER", null ], "description": "The weight of the qualifying question (e.g., INSTANT_DISQUALIFIER)" } }, "required": [ "answer", "rationale", "confidence", "question" ] } }, "score": { "type": "number", "nullable": true }, "rationale": { "type": "string", "nullable": true } } } } }, "annotations": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string" }, "meta": { "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true } }, "required": [ "type", "title" ] } }, "metadata": { "nullable": true } } }, "customTask": { "type": "object", "nullable": true, "properties": { "content": { "nullable": true, "description": "Structured JSON output from the custom task" }, "error": { "type": "string", "nullable": true, "description": "Error message if the custom task failed" } } }, "disqualifierSummary": { "type": "object", "nullable": true, "properties": { "triggered": { "type": "boolean" }, "firstQuestion": { "type": "string", "nullable": true }, "firstRationale": { "type": "string", "nullable": true }, "totalCount": { "type": "number" } }, "required": [ "triggered", "firstQuestion", "firstRationale", "totalCount" ] } }, "required": [ "score", "rationale", "product", "service", "solution", "segment", "playbook" ] }, "ProspectorAgentData": { "type": "object", "nullable": true, "properties": { "contacts": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/ProspectorContact" } }, "count": { "type": "number", "nullable": true } } }, "ProspectorContact": { "type": "object", "properties": { "contact": { "type": "object", "nullable": true, "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "profileUrl": { "type": "string", "nullable": true }, "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "founded": { "type": "number", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "nullable": true }, "locality": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "streetAddress": { "type": "string", "nullable": true } } }, "employeeCount": { "type": "number", "nullable": true }, "followerCount": { "type": "number", "nullable": true }, "type": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "specialties": { "type": "array", "nullable": true, "items": { "type": "string" } }, "industry": { "type": "string", "nullable": true }, "crunchBaseFunding": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "fundingRoundCount": { "type": "number", "nullable": true }, "roundDate": { "type": "string", "nullable": true, "format": "date-time" }, "roundName": { "type": "string", "nullable": true }, "investorNames": { "type": "array", "nullable": true, "items": { "type": "string" } }, "investorCount": { "type": "number", "nullable": true }, "roundAmount": { "type": "number", "nullable": true }, "roundCurrency": { "type": "string", "nullable": true } } } } } }, "companyName": { "type": "string", "nullable": true }, "companyDomain": { "type": "string", "nullable": true }, "companyFoundedYear": { "type": "number", "nullable": true }, "companyEmployeeCount": { "type": "number", "nullable": true }, "companyDescription": { "type": "string", "nullable": true }, "headline": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "slug": { "type": "string", "nullable": true }, "internalPictureUrl": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "currentJobFunction": { "type": "string", "nullable": true }, "currentSeniority": { "type": "string", "nullable": true }, "followers": { "type": "number", "nullable": true }, "allPositionsCount": { "type": "number", "nullable": true }, "currentPositionsCount": { "type": "number", "nullable": true }, "positions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "companyName": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "is_current": { "type": "boolean", "default": false }, "startDate": { "type": "string", "nullable": true, "format": "date-time" }, "endDate": { "type": "string", "nullable": true, "format": "date-time" }, "seniority": { "type": "string", "nullable": true }, "jobFunction": { "type": "string", "nullable": true }, "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "founded": { "type": "number", "nullable": true }, "employeeCount": { "type": "number", "nullable": true }, "description": { "type": "string", "nullable": true }, "location": { "type": "object", "nullable": true, "properties": { "region": { "type": "string", "nullable": true }, "locality": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "streetAddress": { "type": "string", "nullable": true } } }, "slug": { "type": "string", "nullable": true } } } } } } } }, "lookalikeSource": { "type": "string", "nullable": true }, "personas": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/NameAndOId" } } } }, "CallPrepAgentData": { "type": "object", "nullable": true, "properties": { "discoveryQuestions": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [] }, "callScript": { "type": "string", "nullable": true }, "personBrief": { "type": "string", "nullable": true }, "companyBrief": { "type": "string", "nullable": true }, "objectionHandling": { "type": "string", "nullable": true }, "relevantCaseStudies": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "whyIsThisRelevant": { "type": "array", "items": { "type": "string" } }, "keyPointsToFocusOn": { "type": "array", "items": { "type": "string" } }, "keyDifferences": { "type": "array", "items": { "type": "string" } }, "snippet": { "type": "string" }, "referenceCustomerName": { "type": "string", "nullable": true }, "matchConfidence": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", null ] }, "matchAnalysis": { "type": "string", "nullable": true } }, "required": [ "whyIsThisRelevant", "keyPointsToFocusOn", "keyDifferences", "snippet" ] } }, "product": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "service": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "solution": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "playbook": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "persona": { "$ref": "#/components/schemas/LibraryEntitySlot" }, "useCases": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "referenceCustomers": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "alternatives": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "buyingTriggers": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "coreFeatures": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "objections": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/LibraryEntitySlot" } }, "resultUrl": { "type": "string", "nullable": true }, "annotations": { "type": "object", "nullable": true, "properties": { "annotations": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string" }, "meta": { "nullable": true }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true } }, "required": [ "type", "title" ] } }, "metadata": { "nullable": true } } }, "customTask": { "type": "object", "nullable": true, "properties": { "content": { "nullable": true, "description": "Structured JSON output from the custom task" }, "error": { "type": "string", "nullable": true, "description": "Error message if the custom task failed" } } } } }, "CompetitorData": { "type": "object", "nullable": true, "properties": { "howTheyPosition": { "type": "array", "items": { "type": "string" } }, "ourKeyDifferentiators": { "type": "array", "items": { "type": "string" } }, "competitorStrengths": { "type": "array", "items": { "type": "string" } }, "competitorWeaknesses": { "type": "array", "items": { "type": "string" } }, "reasonsWeWin": { "type": "array", "items": { "type": "string" } }, "reasonsWeLose": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "howTheyPosition", "ourKeyDifferentiators", "competitorStrengths", "competitorWeaknesses", "reasonsWeWin", "reasonsWeLose" ] }, "Competitor": { "type": "object", "properties": { "oId": { "type": "string", "description": "Competitor OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Competitor name" }, "internalName": { "type": "string", "description": "Competitor internal name" }, "description": { "type": "string", "nullable": true, "description": "Competitor description" }, "url": { "type": "string", "nullable": true, "description": "The competitor's canonical web URL (company homepage or product page), or null if unknown.", "example": "https://salesforce.com" }, "firmographics": { "type": "object", "nullable": true, "properties": { "overview": { "type": "string", "nullable": true }, "annualRecurringRevenueUsd": { "type": "number", "nullable": true, "minimum": 0 }, "annualRecurringRevenueEstimated": { "type": "boolean" }, "employeeCount": { "type": "integer", "nullable": true, "minimum": 0 }, "employeeCountEstimated": { "type": "boolean" }, "fundingTotalUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRound": { "type": "string", "nullable": true }, "latestFundingRoundAmountUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRoundDate": { "type": "string", "nullable": true }, "foundedYear": { "type": "integer", "nullable": true, "minimum": 1000, "maximum": 3000 }, "headquarters": { "type": "string", "nullable": true }, "marketSharePercent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "marketShareMarket": { "type": "string", "nullable": true }, "marketShareEstimated": { "type": "boolean" }, "websiteUrl": { "type": "string", "nullable": true, "format": "uri" }, "careersUrl": { "type": "string", "nullable": true, "format": "uri" }, "blogUrl": { "type": "string", "nullable": true, "format": "uri" }, "g2Url": { "type": "string", "nullable": true, "format": "uri" }, "citations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "researchedAt": { "type": "string", "format": "date-time" } }, "required": [ "overview", "annualRecurringRevenueUsd", "annualRecurringRevenueEstimated", "employeeCount", "employeeCountEstimated", "fundingTotalUsd", "latestFundingRound", "latestFundingRoundAmountUsd", "latestFundingRoundDate", "foundedYear", "headquarters", "marketSharePercent", "marketShareMarket", "marketShareEstimated", "websiteUrl", "careersUrl", "blogUrl", "g2Url", "citations", "researchedAt" ] }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/CompetitorData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the competitor", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the competitor", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "name", "internalName" ] }, "CompetitorGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the competitor - if provided, will be used as the entity name", "example": "Salesforce CRM" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the competitor analysis from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of competitor generation requests - each object generates one competitor analysis", "example": [ { "name": "Salesforce CRM", "sources": [ { "type": "TEXT", "value": "Direct competitor in the CRM space with enterprise focus and strong sales automation" } ] }, { "sources": [ { "type": "URL", "value": "https://example.com/competitor-analysis" } ] } ] }, "AlternativeData": { "type": "object", "nullable": true, "properties": { "whereItWorks": { "type": "array", "items": { "type": "string" } }, "whereItBreaks": { "type": "array", "items": { "type": "string" } }, "whoChampionsThisApproach": { "type": "array", "items": { "type": "string" } }, "whyOurApproachIsSuperior": { "type": "array", "items": { "type": "string" } }, "perceivedBenefits": { "type": "array", "items": { "type": "string" } }, "hiddenCostsAndPitfalls": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whereItWorks", "whereItBreaks", "whoChampionsThisApproach", "whyOurApproachIsSuperior", "perceivedBenefits", "hiddenCostsAndPitfalls" ] }, "Alternative": { "type": "object", "properties": { "oId": { "type": "string", "description": "Alternative OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Alternative name" }, "internalName": { "type": "string", "description": "Alternative internal name" }, "description": { "type": "string", "nullable": true, "description": "Alternative description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/AlternativeData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the alternative", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the alternative", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "oId", "createdAt", "name", "internalName" ] }, "AlternativeGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the alternative - if provided, will be used as the entity name", "example": "Spreadsheet + email stack" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the alternative analysis from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of alternative generation requests - each object generates one status-quo / incumbent analysis" }, "BuyingTriggerData": { "type": "object", "nullable": true, "properties": { "whyThisCreatesUrgency": { "type": "array", "items": { "type": "string" } }, "whoFeelsThisMost": { "type": "array", "items": { "type": "string" } }, "costOfInaction": { "type": "array", "items": { "type": "string" } }, "howWeHelpInThisMoment": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whyThisCreatesUrgency", "whoFeelsThisMost", "costOfInaction", "howWeHelpInThisMoment" ] }, "BuyingTrigger": { "type": "object", "properties": { "oId": { "type": "string", "description": "Buying trigger OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Buying trigger name" }, "internalName": { "type": "string", "description": "Buying trigger internal name" }, "description": { "type": "string", "nullable": true, "description": "Buying trigger description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/BuyingTriggerData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the buying trigger", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the buying trigger", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "oId", "createdAt", "name", "internalName" ] }, "BuyingTriggerGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the buying trigger - if provided, will be used as the entity name", "example": "New CTO hired" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the buying trigger analysis from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of buying trigger generation requests - each object generates one buying trigger analysis" }, "CoreFeatureData": { "type": "object", "nullable": true, "properties": { "whatItDoes": { "type": "array", "items": { "type": "string" } }, "howItWorks": { "type": "array", "items": { "type": "string" } }, "whatItImpacts": { "type": "array", "items": { "type": "string" } }, "whyThisExists": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whatItDoes", "howItWorks", "whatItImpacts", "whyThisExists" ] }, "CoreFeature": { "type": "object", "properties": { "oId": { "type": "string", "description": "Core Feature OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Core Feature name" }, "internalName": { "type": "string", "description": "Core Feature internal name" }, "description": { "type": "string", "nullable": true, "description": "Core Feature description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/CoreFeatureData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the core feature", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the core feature", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" }, "offering": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "type": { "type": "string", "enum": [ "product", "service", "solution" ] }, "name": { "type": "string", "nullable": true } }, "required": [ "oId", "type" ] } }, "required": [ "oId", "createdAt", "name", "internalName" ] }, "CoreFeatureGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the core feature - if provided, will be used as the entity name", "example": "Real-time Deal Risk Alerts" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the core feature analysis from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of core feature generation requests - each object generates one named capability" }, "ObjectionData": { "type": "object", "nullable": true, "properties": { "underlyingConcern": { "type": "array", "items": { "type": "string" } }, "assumptionsAndMisconceptions": { "type": "array", "items": { "type": "string" } }, "areasToProbeAndClarify": { "type": "array", "items": { "type": "string" } }, "reframeAndResponse": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "underlyingConcern", "assumptionsAndMisconceptions", "areasToProbeAndClarify", "reframeAndResponse" ] }, "Objection": { "type": "object", "properties": { "oId": { "type": "string", "description": "Objection OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Objection name" }, "internalName": { "type": "string", "description": "Objection internal name" }, "description": { "type": "string", "nullable": true, "description": "Objection description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/ObjectionData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the objection", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the objection", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "oId", "createdAt", "name", "internalName" ] }, "ObjectionGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional label for the objection \u2014 if provided, will be used as the generation seed", "example": "Implementation looks too heavy" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the objection handling content from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of objection generation requests \u2014 each object generates one objection" }, "SegmentData": { "type": "object", "nullable": true, "properties": { "strategicFit": { "type": "array", "items": { "type": "string" }, "default": [] }, "firmographics": { "type": "object", "properties": { "industry": { "type": "array", "items": { "type": "string" }, "default": [] }, "businessModel": { "type": "array", "items": { "type": "string" }, "default": [] }, "geography": { "type": "array", "items": { "type": "string" }, "default": [] }, "revenue": { "type": "array", "items": { "type": "string" }, "default": [] }, "employees": { "type": "array", "items": { "type": "string" }, "default": [] } }, "default": { "industry": [], "businessModel": [], "geography": [], "revenue": [], "employees": [] }, "additionalProperties": { "nullable": true } }, "operatingCharacteristics": { "type": "array", "items": { "type": "string" }, "default": [] }, "strategicPriorities": { "type": "array", "items": { "type": "string" }, "default": [] }, "marketPressures": { "type": "array", "items": { "type": "string" }, "default": [] }, "buyingDynamics": { "type": "array", "items": { "type": "string" }, "default": [] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "Segment": { "type": "object", "properties": { "oId": { "type": "string", "description": "Segment OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "description": "Segment name" }, "internalName": { "type": "string", "description": "Segment internal name" }, "description": { "type": "string", "nullable": true, "description": "Segment description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/SegmentData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] }, "description": "Qualifying questions" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the segment", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the segment", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" }, "unrecognized": { "type": "boolean" }, "rejected": { "type": "boolean" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "tagGroupOId": { "type": "string" }, "tagGroupName": { "type": "string" }, "tagOId": { "type": "string" }, "tagName": { "type": "string" } }, "required": [ "tagGroupOId", "tagGroupName", "tagOId", "tagName" ] } } }, "required": [ "oId", "createdAt", "name", "internalName", "unrecognized", "rejected" ] }, "SegmentGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the segment - if provided, will be used as the entity name", "example": "Enterprise Technology Companies" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the market segment from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of segment generation requests - each object generates one market segment", "example": [ { "name": "Enterprise Technology Companies", "sources": [ { "type": "TEXT", "value": "Enterprise companies with 500+ employees in technology sector" } ] }, { "sources": [ { "type": "URL", "value": "https://example.com/market-research" } ] } ] }, "ProofPointData": { "type": "object", "nullable": true, "properties": { "theProof": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whatItSupports": { "type": "array", "nullable": true, "items": { "type": "string" } }, "howWeTalkAboutThis": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whyItMatters": { "type": "array", "nullable": true, "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "stat", "fact", "quote", "award", "recognition", "other" ] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "ProofPoint": { "type": "object", "properties": { "oId": { "type": "string", "description": "Proof Point OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Proof Point name" }, "internalName": { "type": "string", "description": "Proof Point internal name" }, "description": { "type": "string", "nullable": true, "description": "Proof Point description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/ProofPointData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the proof point", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the proof point", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] }, "ProofPointGenerationInputs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Optional name for the proof point - if provided, will be used as the entity name", "example": "50% Sales Improvement Case Study" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the proof point from" } }, "required": [ "sources" ] }, "minItems": 1, "description": "Array of proof point generation requests - each object generates one proof point", "example": [ { "name": "50% Sales Improvement Case Study", "sources": [ { "type": "TEXT", "value": "Customer success story showing 50% improvement in sales conversion rates" } ] }, { "sources": [ { "type": "URL", "value": "https://example.com/case-study" } ] } ] }, "ContextAgentData": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSONA", "USE_CASE", "REFERENCE_CUSTOMER", "PROOF_POINT", "SEGMENT", "COMPETITOR", "ALTERNATIVE", "BUYING_TRIGGER", "OBJECTION", "PRODUCT", "SERVICE", "PLAYBOOK", "HYPOTHESIS", "SKILL", "PERSON_LINKEDIN", "COMPANY_WEBSITE", "COMPANY_RESEARCH", "PERSON_RESEARCH", "WEB_SEARCH", "CRM_CONTEXT", "GLOBAL_RESOURCE", "WEBSITE_RESOURCE" ], "description": "Type/source of this context document" }, "id": { "type": "string", "description": "Unique identifier (oId for library entities, external_id for resources)" }, "name": { "type": "string", "nullable": true, "description": "Name or title of the document" }, "data": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "Document content/details" }, "score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 10, "description": "Reranking relevance score (0-10 scale) - only present if reranking was applied" }, "reasoning": { "type": "string", "nullable": true, "description": "Explanation of why this document is relevant (if reasoning.perDocument enabled)" } }, "required": [ "type", "id" ] }, "description": "Array of context documents" }, "reasoning": { "type": "string", "nullable": true, "description": "Overall summary of how documents help answer query (if reasoning.overall enabled)" } }, "required": [ "documents" ] }, "ContextData": { "type": "object", "properties": { "documents": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PERSONA", "USE_CASE", "REFERENCE_CUSTOMER", "PROOF_POINT", "SEGMENT", "COMPETITOR", "ALTERNATIVE", "BUYING_TRIGGER", "OBJECTION", "PRODUCT", "SERVICE", "PLAYBOOK", "HYPOTHESIS", "SKILL", "PERSON_LINKEDIN", "COMPANY_WEBSITE", "COMPANY_RESEARCH", "PERSON_RESEARCH", "WEB_SEARCH", "CRM_CONTEXT", "GLOBAL_RESOURCE", "WEBSITE_RESOURCE" ], "description": "Type/source of this context document" }, "id": { "type": "string", "description": "Unique identifier (oId for library entities, external_id for resources)" }, "name": { "type": "string", "nullable": true, "description": "Name or title of the document" }, "data": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "Document content/details" }, "score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 10, "description": "Reranking relevance score (0-10 scale) - only present if reranking was applied" }, "reasoning": { "type": "string", "nullable": true, "description": "Explanation of why this document is relevant (if reasoning.perDocument enabled)" } }, "required": [ "type", "id" ] }, "description": "Array of context documents" }, "reasoning": { "type": "string", "nullable": true, "description": "Overall summary of how documents help answer query (if reasoning.overall enabled)" }, "_debug": { "type": "object", "nullable": true, "properties": { "totalFetched": { "type": "number", "description": "Total documents fetched before reranking" }, "afterReranking": { "type": "number", "description": "Documents remaining after reranking" }, "timeTaken": { "type": "number", "nullable": true, "description": "Total request time in milliseconds" }, "sourcesUsed": { "type": "object", "properties": { "library": { "type": "boolean" }, "resources": { "type": "boolean" }, "tools": { "type": "boolean" } }, "required": [ "library", "resources", "tools" ] }, "tokenUsage": { "type": "object", "nullable": true, "properties": { "inputTokens": { "type": "number", "description": "Input tokens consumed" }, "outputTokens": { "type": "number", "description": "Output tokens generated" }, "totalTokens": { "type": "number", "description": "Total tokens (input + output)" } }, "required": [ "inputTokens", "outputTokens", "totalTokens" ], "description": "LLM token consumption breakdown" } }, "required": [ "totalFetched", "afterReranking", "sourcesUsed" ], "description": "Admin-only debug information" } }, "required": [ "documents" ] }, "BrandVoice": { "type": "object", "properties": { "oId": { "type": "string", "description": "Brand Voice OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "name": { "type": "string", "description": "Brand Voice name" }, "data": { "$ref": "#/components/schemas/BrandVoiceData" }, "default": { "type": "boolean", "default": false, "description": "Whether this is the default brand voice for the workspace" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "oId", "createdAt", "updatedAt", "name" ] }, "BrandVoiceData": { "type": "object", "nullable": true, "properties": { "title": { "type": "string", "description": "The name/title of the brand voice", "example": "Enterprise Brand Voice" }, "description": { "type": "string", "description": "High-level description of this brand voice", "example": "Professional and authoritative tone for enterprise audiences" }, "essence": { "type": "string", "nullable": true, "description": "The core essence or soul of the brand voice", "example": "Clear, concise, and confident" }, "personality": { "type": "object", "properties": { "coreTraits": { "type": "array", "items": { "type": "string" }, "description": "Core personality traits that define the brand voice", "example": [ "Professional", "Authoritative", "Empathetic" ] }, "guidingPrinciples": { "type": "array", "items": { "type": "string" }, "description": "Guiding principles for communication style", "example": [ "Clarity over cleverness", "Lead with value" ] } }, "required": [ "coreTraits", "guidingPrinciples" ], "description": "Brand personality definition" }, "tonality": { "type": "object", "properties": { "soundLike": { "type": "array", "items": { "type": "string" }, "description": "Desired tonal qualities the brand should embody", "example": [ "Confident expert", "Trusted advisor" ] }, "neverSoundLike": { "type": "array", "items": { "type": "string" }, "description": "Tonal qualities the brand should avoid", "example": [ "Pushy salesperson", "Corporate jargon" ] } }, "required": [ "soundLike", "neverSoundLike" ], "description": "Brand tonality guidelines" }, "vocabulary": { "type": "object", "properties": { "keyCompanyTerms": { "type": "array", "items": { "type": "string" }, "description": "Preferred company-specific terminology", "example": [ "Octave", "knowledge graph", "GTM intelligence" ] }, "keySubstitutions": { "type": "array", "items": { "type": "string" }, "description": "Word or phrase substitutions to enforce", "example": [ "Say 'revenue team' not 'sales team'" ] } }, "required": [ "keyCompanyTerms", "keySubstitutions" ], "description": "Vocabulary preferences and terminology" }, "writingRules": { "type": "object", "properties": { "languageRules": { "type": "array", "items": { "type": "string" }, "description": "Grammatical and language rules to follow", "example": [ "Use active voice", "Avoid passive constructions" ] }, "formattingFundamentals": { "type": "array", "items": { "type": "string" }, "description": "Formatting guidelines for content structure", "example": [ "Short paragraphs", "Bullet points for lists" ] } }, "required": [ "languageRules", "formattingFundamentals" ], "description": "Writing style and formatting rules" }, "audienceConsiderations": { "type": "object", "properties": { "qualitiesAndCharacteristics": { "type": "array", "items": { "type": "string" }, "description": "Key qualities and characteristics of the target audience", "example": [ "Technical decision makers", "Data-driven professionals" ] }, "aspirationsAndBoundaries": { "type": "array", "items": { "type": "string" }, "description": "Audience aspirations to address and communication boundaries to respect", "example": [ "Want actionable insights", "No fluff or filler" ] } }, "required": [ "qualitiesAndCharacteristics", "aspirationsAndBoundaries" ], "description": "Target audience considerations" }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" } }, "required": [ "title", "description", "personality", "tonality", "vocabulary", "writingRules", "audienceConsiderations" ] }, "BrandVoiceList": { "type": "object", "properties": { "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BrandVoice" } } }, "required": [ "hasNext", "total", "data" ] }, "Asset": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Asset UUID \u2014 the id used by every asset_* tool. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "identifier": { "type": "string", "description": "Human-readable identifier/slug. e.g. 'q3-launch-microsite'" }, "description": { "type": "string", "description": "Free-text description. e.g. 'Q3 product launch landing page'" }, "type": { "type": "string", "enum": [ "website", "storage", "skill" ], "description": "Kind of asset. One of: website (served as a hosted site), storage (downloadable files), skill (Agent Skill folder \u2014 managed via the skill tools). e.g. 'website'" }, "entryPoint": { "type": "string", "nullable": true, "description": "File served at the site root; null for storage assets. e.g. 'index.html'" }, "storagePath": { "type": "string", "nullable": true, "description": "Internal storage path; null until files are stored. e.g. 'workspaces/ws_1/assets/4f1e2a90'" }, "currentVersion": { "type": "number", "description": "Version the asset's URL serves right now; changes on file updates and on asset_version_restore. e.g. 3" }, "latestVersion": { "type": "number", "description": "Highest version ever minted (the high-water mark) \u2014 greater than currentVersion after a rollback. e.g. 4" }, "vanitySlug": { "type": "string", "nullable": true, "description": "Workspace-unique vanity slug, set via asset_update; null when the asset has none. e.g. 'q3-launch'" }, "vanityUrl": { "type": "string", "nullable": true, "description": "Friendly URL built from the workspace's vanity handle + vanitySlug; null until a slug is set. e.g. 'https://sites.octave.app/s/acme/q3-launch/'" }, "siteUrl": { "type": "string", "nullable": true, "description": "Public URL of the served site; null until published. e.g. 'https://sites.octave.app/4f1e2a90'" }, "previewUrl": { "type": "string", "nullable": true, "description": "Tokenized link to preview this asset while it isn't publicly servable yet (privacy is only_me/workspace, or status is unpublished) \u2014 the owner or a workspace teammate can open it even though the public URL 404s. null once published + public (use siteUrl). e.g. 'https://sites.octave.app/preview/eyJ...'" }, "thumbnailUrl": { "type": "string", "nullable": true, "description": "Screenshot of the site, gated like the asset itself: a plain URL once published + public, tokenized otherwise. Null is normal \u2014 storage assets never have one, website screenshots are rendered asynchronously after upload, and a failed render stays null. e.g. 'https://sites.octave.app/thumbnails/4f1e2a90.jpg'" }, "status": { "type": "string", "enum": [ "published", "unpublished" ], "description": "Lifecycle status. One of: published (default; discoverable), unpublished (hidden, still readable by uuid). Independent of privacy \u2014 publishing does NOT make an asset public; set privacy to 'public' for that. e.g. 'published'" }, "privacy": { "type": "string", "enum": [ "only_me", "workspace", "public" ], "description": "Who can access it \u2014 an ordered ladder, each tier strictly more permissive: only_me (owner only), workspace (default; owner + workspace members), public (anyone with the URL). e.g. 'workspace'" }, "externallyShared": { "type": "boolean", "description": "Derived, read-only: true when privacy isn't public and the asset has at least one active share link (i.e. it's shared with specific people/domains outside the workspace). Creating/revoking a share link changes this, not asset_update. e.g. false" }, "openLink": { "type": "boolean", "description": "Derived, read-only: true when privacy isn't public and at least one active share link admits ANYONE holding it (access: 'anyone'). The sharper half of externallyShared \u2014 that says some outsiders can see this, this says anyone with the URL can, which the privacy tier alone would hide. Report it wherever you report the tier. e.g. false" }, "owner": { "type": "string", "description": "Who owns the asset, from your perspective: 'me' for your own assets, otherwise the owner's 'First Last ' (a workspace teammate). e.g. 'me'" }, "ownerEmail": { "type": "string", "nullable": true, "default": null, "description": "The owner's email as a structured field \u2014 always the real identity, even when `owner` reads 'me'. Null for assets created before owner-identity capture (or when the artifacts service predates the field). e.g. 'ada@acme.com'" }, "metadata": { "type": "object", "properties": { "filesMap": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "File name. e.g. 'index.html'" }, "size": { "type": "number", "description": "File size in bytes. e.g. 20480" }, "mimeType": { "type": "string", "description": "MIME type. e.g. 'text/html'" }, "path": { "type": "string", "description": "Path within the asset. e.g. '/index.html'" }, "createdAt": { "type": "string", "description": "ISO-8601 time the file was stored. e.g. '2026-07-03T10:15:00.000Z'" } }, "required": [ "filename", "size", "mimeType", "path", "createdAt" ] }, "description": "Flat list of every file in the asset." }, "siteMap": { "type": "object", "nullable": true, "properties": { "totalFiles": { "type": "number", "description": "Total number of files in the site. e.g. 12" }, "totalSize": { "type": "number", "description": "Total size of the site in bytes. e.g. 348160" }, "entryPoint": { "type": "string", "description": "File served at the site root. e.g. 'index.html'" }, "root": { "$ref": "#/components/schemas/AssetSiteMapDirNode" } }, "required": [ "totalFiles", "totalSize", "entryPoint", "root" ], "description": "Directory tree of the site; null if not yet computed." } }, "required": [ "filesMap", "siteMap" ], "description": "File metadata for the asset." }, "skillMetadata": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "description" ], "description": "Parsed SKILL.md frontmatter \u2014 only set for skill-type artifacts; null otherwise." }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-01T09:00:00.000Z'" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update time. e.g. '2026-07-03T12:30:00.000Z'" } }, "required": [ "uuid", "identifier", "description", "type", "entryPoint", "storagePath", "currentVersion", "latestVersion", "vanitySlug", "vanityUrl", "siteUrl", "previewUrl", "thumbnailUrl", "status", "privacy", "externallyShared", "openLink", "owner", "ownerEmail", "metadata", "skillMetadata", "createdAt", "updatedAt" ] }, "AssetSiteMapDirNode": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dir" ] }, "name": { "type": "string", "description": "Directory name. e.g. 'assets'" }, "path": { "type": "string", "description": "Directory path. e.g. '/assets'" }, "fileCount": { "type": "number", "description": "Number of files under this directory, recursive. e.g. 8" }, "totalSize": { "type": "number", "description": "Total bytes under this directory, recursive. e.g. 51200" }, "children": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "name": { "type": "string", "description": "File name. e.g. 'index.html'" }, "path": { "type": "string", "description": "Path within the asset. e.g. '/assets/app.js'" }, "size": { "type": "number", "description": "File size in bytes. e.g. 4096" }, "mimeType": { "type": "string", "description": "MIME type. e.g. 'text/javascript'" }, "isEntryPoint": { "type": "boolean", "description": "True if this file is the site's entry point. e.g. false" } }, "required": [ "type", "name", "path", "size", "mimeType", "isEntryPoint" ] }, { "$ref": "#/components/schemas/AssetSiteMapDirNode" } ] }, "description": "Child files and subdirectories." } }, "required": [ "type", "name", "path", "fileCount", "totalSize", "children" ], "description": "Root node of the site's directory tree." }, "MotionListItem": { "type": "object", "properties": { "oId": { "type": "string", "description": "Motion oId" }, "name": { "type": "string", "description": "Motion name" }, "description": { "type": "string", "nullable": true }, "overview": { "type": "array", "items": { "type": "string" } }, "offeringId": { "type": "string" }, "offeringName": { "type": "string" }, "offeringType": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ] }, "motionType": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ], "description": "Motion type" }, "methodologyType": { "type": "string", "enum": [ "OCTAVE", "CVI" ] }, "icpCount": { "type": "number" }, "playbookCount": { "type": "number" }, "compositionCount": { "type": "number" }, "defaultPlaybookOId": { "type": "string", "nullable": true }, "createdByUserOId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" } }, "required": [ "oId", "name", "offeringId", "offeringName", "offeringType", "motionType", "methodologyType", "icpCount", "playbookCount", "compositionCount", "createdAt", "updatedAt" ] }, "Motion": { "type": "object", "properties": { "oId": { "type": "string", "description": "Motion oId" }, "name": { "type": "string", "description": "Motion name" }, "description": { "type": "string", "description": "Motion description" }, "offering": { "type": "object", "properties": { "oId": { "type": "string" }, "type": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true } }, "required": [ "oId", "type", "name" ] }, "srcOffering": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "type": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true } }, "required": [ "oId", "type", "name" ] }, "competitor": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true } }, "required": [ "oId", "name" ] }, "coreFeatures": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true } }, "required": [ "oId", "name" ] }, "default": [] }, "motionType": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ], "description": "Motion type" }, "data": { "type": "object", "properties": { "overview": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [] }, "scope": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [] }, "additionalContext": { "type": "string", "default": "" }, "attachedSources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" }, "displayValue": { "type": "string" } }, "required": [ "type", "value" ] }, "default": [] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } }, "guidingNotes": { "type": "object", "additionalProperties": { "type": "string" } } } }, "defaultPlaybookOId": { "type": "string", "nullable": true, "description": "Default playbook oId" }, "createdByUserOId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" } }, "required": [ "oId", "name", "offering", "motionType", "data", "createdAt", "updatedAt" ] }, "MotionPlaybookListItem": { "type": "object", "properties": { "oId": { "type": "string", "description": "Motion playbook oId" }, "name": { "type": "string", "nullable": true }, "motionOId": { "type": "string", "description": "Parent motion oId" }, "motionName": { "type": "string" }, "offeringName": { "type": "string" }, "motionType": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ] }, "narrativeType": { "type": "string", "nullable": true, "enum": [ "DEFAULT", "THEMATIC", "MILESTONE", "ACCOUNT", "COMPETITIVE", "GEO", "CUSTOM", null ] }, "motionFraming": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } }, "required": [ "oId", "firstName", "lastName" ] }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" } }, "required": [ "oId", "name", "motionOId", "motionName", "offeringName", "motionType", "narrativeType", "motionFraming", "active", "user", "createdAt", "updatedAt" ] }, "MotionPlaybook": { "type": "object", "properties": { "oId": { "type": "string", "description": "Motion playbook oId" }, "motionOId": { "type": "string", "description": "Parent motion oId" }, "name": { "type": "string", "nullable": true, "description": "Playbook name" }, "narrativeType": { "type": "string", "nullable": true, "enum": [ "DEFAULT", "THEMATIC", "MILESTONE", "ACCOUNT", "COMPETITIVE", "GEO", "CUSTOM", null ] }, "narrativeInput": { "type": "string", "nullable": true }, "competitorOIds": { "type": "array", "nullable": true, "items": { "type": "string" } }, "accountDomain": { "type": "string", "nullable": true }, "buyingTriggerOId": { "type": "string", "nullable": true }, "motionFraming": { "type": "string", "nullable": true }, "keyMessaging": { "type": "array", "nullable": true, "items": { "type": "string" } }, "keyPositioning": { "type": "array", "nullable": true, "items": { "type": "string" } }, "scope": { "type": "object", "nullable": true, "properties": { "icpScopeMode": { "type": "string", "enum": [ "AUTO", "MANUAL" ] }, "allSegments": { "type": "boolean" }, "segmentOIds": { "type": "array", "items": { "type": "string" } }, "allPersonas": { "type": "boolean" }, "personaOIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "icpScopeMode", "allSegments", "segmentOIds", "allPersonas", "personaOIds" ] }, "anchorOverrides": { "type": "object", "nullable": true, "properties": { "useCases": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "oIds" ] }, "references": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "oIds" ] }, "proofPoints": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "oIds" ] }, "alternatives": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "default": { "mode": "AUTO", "oIds": [] }, "required": [ "mode", "oIds" ] }, "buyingTriggers": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "default": { "mode": "AUTO", "oIds": [] }, "required": [ "mode", "oIds" ] }, "coreFeatures": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "default": { "mode": "AUTO", "oIds": [] }, "required": [ "mode", "oIds" ] }, "objections": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "default": { "mode": "AUTO", "oIds": [] }, "required": [ "mode", "oIds" ] } }, "required": [ "useCases", "references", "proofPoints" ] }, "additionalContext": { "type": "string", "nullable": true }, "additionalContextSources": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "GOOGLE_DRIVE_FILE_ID", "GENERATIVE_NAME", "OID", "COMPANY_NAME", "FIELDWISE_DOCUMENT_ID", "RAG_DOCUMENT_ID", "RESOURCE", "REPORT", "REPORT_SECTION", "EVENT_OID_FINDINGS", "FINDING_OIDS" ] }, "value": { "type": "string" }, "name": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "useNameIfUrlFails": { "type": "boolean", "nullable": true } }, "required": [ "type", "value" ] } }, "brandVoiceOId": { "type": "string", "nullable": true }, "additionalProperties": { "type": "object", "nullable": true, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } }, "active": { "type": "boolean", "description": "Whether the playbook is active" }, "lastNarrativeGeneratedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" } }, "required": [ "oId", "motionOId", "name", "narrativeType", "narrativeInput", "competitorOIds", "accountDomain", "buyingTriggerOId", "motionFraming", "keyMessaging", "keyPositioning", "scope", "anchorOverrides", "additionalContext", "additionalContextSources", "brandVoiceOId", "additionalProperties", "active", "lastNarrativeGeneratedAt", "createdAt", "updatedAt" ] }, "MotionIcpListItem": { "type": "object", "properties": { "oId": { "type": "string", "description": "Motion ICP oId (micp_ prefix)" }, "motionPlaybookOId": { "type": "string", "description": "Parent motion playbook oId" }, "persona": { "$ref": "#/components/schemas/EntityRef" }, "segment": { "allOf": [ { "$ref": "#/components/schemas/EntityRef" }, { "description": "Target segment" } ] }, "status": { "type": "string", "enum": [ "PENDING_INITIAL_VERSION", "HAS_VERSION", "GENERATING_INITIAL_VERSION", "RUNNING_REPORT", "ANALYZING_LEARNINGS", "ANALYZING_ICP_RECOMMENDATIONS", "UPDATING_VERSION" ], "description": "Current generation status" }, "disabled": { "type": "boolean", "description": "Whether this ICP cell is disabled" } }, "required": [ "oId", "motionPlaybookOId", "persona", "segment", "status", "disabled" ] }, "EntityRef": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "oId", "name" ], "description": "Target persona" }, "MotionIcpDetail": { "type": "object", "properties": { "oId": { "type": "string", "description": "Motion ICP oId (micp_ prefix)" }, "motionPlaybookOId": { "type": "string", "description": "Parent motion playbook oId" }, "persona": { "$ref": "#/components/schemas/EntityRef" }, "segment": { "allOf": [ { "$ref": "#/components/schemas/EntityRef" }, { "description": "Target segment" } ] }, "status": { "type": "string", "enum": [ "PENDING_INITIAL_VERSION", "HAS_VERSION", "GENERATING_INITIAL_VERSION", "RUNNING_REPORT", "ANALYZING_LEARNINGS", "ANALYZING_ICP_RECOMMENDATIONS", "UPDATING_VERSION" ], "description": "Current generation status" }, "disabled": { "type": "boolean", "description": "Whether this ICP cell is disabled" }, "narrative": { "type": "object", "nullable": true, "properties": { "targetIcpOverview": { "type": "string" }, "operatingLandscape": { "type": "array", "items": { "type": "string" } }, "strategicNarrative": { "type": "array", "items": { "type": "string" } }, "painsAndConsequences": { "type": "array", "items": { "type": "string" } }, "benefitsAndImpacts": { "type": "array", "items": { "type": "string" } }, "valueProps": { "type": "array", "items": { "type": "string" } }, "approachAngle": { "type": "array", "items": { "type": "string" } }, "businessImpact": { "type": "array", "items": { "type": "string" } }, "uniqueInsight": { "type": "array", "items": { "type": "string" } }, "salesMethodology": { "type": "array", "items": { "type": "object", "properties": { "stageName": { "type": "string" }, "stageObjective": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": { "sectionName": { "type": "string" }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "sectionName", "content" ] } } }, "required": [ "stageName", "sections" ] } } }, "required": [ "targetIcpOverview", "operatingLandscape", "strategicNarrative", "painsAndConsequences", "benefitsAndImpacts", "salesMethodology" ], "description": "AI-generated narrative fields from the active version (targetIcpOverview, strategicNarrative, painsAndConsequences, benefitsAndImpacts, salesMethodology). salesMethodology stageName values are Early Stage / Mid Stage / Late Stage for OCTAVE motions. Null when no active version exists yet." }, "learningsCount": { "type": "integer", "description": "Total number of current learnings for this ICP cell" }, "latestReport": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "description": "Pass to GET /api/v2/report-run/get for full sections" }, "title": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "windowStart": { "type": "string", "nullable": true, "format": "date-time" }, "windowEnd": { "type": "string", "nullable": true, "format": "date-time" }, "comparisonWithPrevious": { "type": "object", "nullable": true, "properties": { "summaryOfChanges": { "type": "string" }, "emphasisShift": { "type": "string" }, "keyDelta": { "type": "string" }, "newThemes": { "type": "array", "items": { "type": "string" } }, "continuingThemes": { "type": "array", "items": { "type": "string" } } }, "description": "What changed vs the prior report period" } }, "required": [ "oId", "title", "summary", "windowStart", "windowEnd", "comparisonWithPrevious" ], "description": "Latest completed report run summary. Only included when includeReport=true." } }, "required": [ "oId", "motionPlaybookOId", "persona", "segment", "status", "disabled", "narrative", "learningsCount" ] }, "MotionIcpElement": { "type": "object", "properties": { "oId": { "type": "string", "description": "Library entity oId" }, "name": { "type": "string", "description": "Library entity name" }, "type": { "type": "string", "enum": [ "useCase", "proofPoint", "referenceCustomer", "competitor", "alternative", "buyingTrigger", "objection" ], "description": "Recommendation category for this element" } }, "required": [ "oId", "name", "type" ] }, "MotionIcpLearning": { "type": "object", "properties": { "oId": { "type": "string", "description": "Learning oId" }, "type": { "type": "string", "enum": [ "KEY_LANGUAGE", "INDUSTRY_TREND", "PAIN_POINT", "VALUE_PROP", "OBJECTION" ], "description": "Learning type" }, "summary": { "type": "string", "description": "Learning summary" }, "confidence": { "type": "number", "nullable": true, "description": "Confidence score (0\u20131)" }, "sourceType": { "type": "string", "enum": [ "AI_GENERATED", "USER_DEFINED" ], "description": "AI-generated or manual" }, "pinned": { "type": "boolean", "description": "Whether the learning is pinned" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "evidenceByChannel": { "type": "object", "additionalProperties": { "type": "number" }, "description": "Count of evidence findings per channel type" } }, "required": [ "oId", "type", "summary", "confidence", "sourceType", "pinned", "createdAt", "evidenceByChannel" ] }, "ReportGroup": { "type": "object", "properties": { "oId": { "type": "string", "description": "Report group oId" }, "title": { "type": "string", "description": "Group title" }, "description": { "type": "string", "description": "Group description" }, "isActive": { "type": "boolean", "description": "Whether the group is active" }, "type": { "type": "string", "enum": [ "user", "system" ], "description": "Group type" }, "aggregationLevel": { "type": "string", "description": "Aggregation level (WEEKLY, MONTHLY, etc.)" }, "configCount": { "type": "number", "description": "Number of active report configs in this group" }, "createdBy": { "type": "string", "description": "Full name of the user who created this group" }, "status": { "type": "string", "enum": [ "running", "paused", "scheduled", "pending" ], "description": "Current scheduling status" }, "nextRunAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Next scheduled run time" }, "lastRun": { "type": "string", "nullable": true, "format": "date-time", "description": "Most recent run completion time" }, "timezone": { "type": "string", "description": "Timezone used for scheduling" } }, "required": [ "oId", "title", "isActive", "type", "aggregationLevel", "configCount", "lastRun" ] }, "ReportGroupDetail": { "type": "object", "properties": { "oId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "isActive": { "type": "boolean", "default": true }, "templateId": { "type": "string" }, "type": { "type": "string", "enum": [ "user", "system" ] }, "aggregationLevel": { "type": "string", "enum": [ "day", "week", "month" ] }, "triggerType": { "type": "string", "enum": [ "scheduled", "push" ] }, "pushTriggers": { "type": "object", "properties": { "clusterCreated": { "type": "array", "items": { "type": "string" } }, "outcomeCreated": { "type": "array", "items": { "type": "string" } }, "eventProcessed": { "type": "array", "items": { "type": "string" } } } }, "filters": { "type": "object", "properties": { "events": { "type": "object", "properties": { "match": { "type": "object", "properties": { "eventCategories": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "CALL", "CRM", "RESOURCE", "REVISION", "SOCIAL", "ADS", "PRODUCT", "UNKNOWN" ] }, "description": "Filter by event categories (CALL, EMAIL, CRM)" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL_SENT", "EMAIL_REPLY_RECEIVED", "CALL_TRANSCRIPT", "DEAL_WON", "DEAL_LOST", "OPPORTUNITY_CREATED", "MEETING_BOOKED", "RESOURCE_INDEXED", "RESOURCE_REINDEXED", "PROJECT_UPDATE", "TASK_COMPLETED", "ENTITY_CREATED", "ENTITY_UPDATED", "SOCIAL_MESSAGE_SENT", "SOCIAL_MESSAGE_RECEIVED", "SOCIAL_CONNECTION_SENT", "SOCIAL_CONNECTION_ACCEPTED", "AD_SET_PUBLISHED", "AD_PERFORMANCE_SNAPSHOT", "BULK_IMPORT_SUMMARY", "PROCESSING_NOT_APPLICABLE", "PROVIDER_EVENT_TYPE_UNKNOWN", "UNKNOWN" ] }, "description": "Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.)" }, "sentiments": { "type": "array", "items": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "UNKNOWN" ] }, "description": "Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED)" }, "contactEmails": { "type": "array", "items": { "type": "string" }, "description": "Filter by participant email addresses" }, "companyDomains": { "type": "array", "items": { "type": "string" }, "description": "Filter by company domains" }, "outcomeFilters": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST", "POSITIVE_REPLY", "NEUTRAL_REPLY", "NEGATIVE_REPLY" ] }, "description": "Filter by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY)" }, "opportunityStatuses": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST" ] }, "description": "Filter by opportunity status (OPEN, WON, LOST)" }, "minDealAmount": { "type": "number", "description": "Minimum deal amount filter" }, "maxDealAmount": { "type": "number", "description": "Maximum deal amount filter" }, "offerings": { "type": "array", "items": { "type": "string" }, "description": "Filter by offering oIds" }, "personas": { "type": "array", "items": { "type": "string" }, "description": "Filter by persona oIds (events must match these personas)" }, "segments": { "type": "array", "items": { "type": "string" }, "description": "Filter by segment oIds" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by reporting tag oIds. Resolved to the segments carrying those tags; multiple tags are OR'd." }, "playbooks": { "type": "array", "items": { "type": "string" }, "description": "Filter by playbook oIds" }, "useCases": { "type": "array", "items": { "type": "string" }, "description": "Filter by use case oIds" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Filter by reference customer oIds" }, "competitors": { "type": "array", "items": { "type": "string" }, "description": "Filter by competitor oIds" }, "alternatives": { "type": "array", "items": { "type": "string" }, "description": "Filter by alternative oIds" }, "buyingTriggers": { "type": "array", "items": { "type": "string" }, "description": "Filter by buying trigger oIds" }, "coreFeatures": { "type": "array", "items": { "type": "string" }, "description": "Filter by core feature oIds" }, "objections": { "type": "array", "items": { "type": "string" }, "description": "Filter by objection oIds" }, "proofPoints": { "type": "array", "items": { "type": "string" }, "description": "Filter by proof point oIds" }, "motionTypes": { "type": "array", "items": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ] }, "description": "Filter by motion type (NET_NEW, UPSELL)" }, "callPurposes": { "type": "array", "items": { "type": "string", "enum": [ "DISCOVERY", "DEMO", "TECHNICAL_EVALUATION", "WORKING_SESSION", "NEGOTIATION_PRICING", "ONBOARDING", "CHECK_IN_SUCCESS", "QBR_RENEWAL", "EXPANSION_UPSELL", "ESCALATION_CHURN_RISK", "SUPPORT", "INTERNAL_SYNC", "OTHER" ] }, "description": "Filter calls by classified purpose (DISCOVERY, DEMO, TECHNICAL_EVALUATION, WORKING_SESSION, NEGOTIATION_PRICING, ONBOARDING, CHECK_IN_SUCCESS, QBR_RENEWAL, EXPANSION_UPSELL, ESCALATION_CHURN_RISK, SUPPORT, INTERNAL_SYNC, OTHER)" }, "unmatchedOnly": { "type": "boolean", "description": "When true, only return events that have findings with no library entity matches" } }, "description": "Filters to INCLUDE events matching these criteria" }, "exclude": { "type": "object", "properties": { "eventCategories": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "CALL", "CRM", "RESOURCE", "REVISION", "SOCIAL", "ADS", "PRODUCT", "UNKNOWN" ] }, "description": "Filter by event categories (CALL, EMAIL, CRM)" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL_SENT", "EMAIL_REPLY_RECEIVED", "CALL_TRANSCRIPT", "DEAL_WON", "DEAL_LOST", "OPPORTUNITY_CREATED", "MEETING_BOOKED", "RESOURCE_INDEXED", "RESOURCE_REINDEXED", "PROJECT_UPDATE", "TASK_COMPLETED", "ENTITY_CREATED", "ENTITY_UPDATED", "SOCIAL_MESSAGE_SENT", "SOCIAL_MESSAGE_RECEIVED", "SOCIAL_CONNECTION_SENT", "SOCIAL_CONNECTION_ACCEPTED", "AD_SET_PUBLISHED", "AD_PERFORMANCE_SNAPSHOT", "BULK_IMPORT_SUMMARY", "PROCESSING_NOT_APPLICABLE", "PROVIDER_EVENT_TYPE_UNKNOWN", "UNKNOWN" ] }, "description": "Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.)" }, "sentiments": { "type": "array", "items": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "UNKNOWN" ] }, "description": "Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED)" }, "contactEmails": { "type": "array", "items": { "type": "string" }, "description": "Filter by participant email addresses" }, "companyDomains": { "type": "array", "items": { "type": "string" }, "description": "Filter by company domains" }, "outcomeFilters": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST", "POSITIVE_REPLY", "NEUTRAL_REPLY", "NEGATIVE_REPLY" ] }, "description": "Exclude by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY)" }, "opportunityStatuses": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST" ] }, "description": "Exclude by opportunity status (OPEN, WON, LOST)" }, "minDealAmount": { "type": "number", "description": "Minimum deal amount filter" }, "maxDealAmount": { "type": "number", "description": "Maximum deal amount filter" }, "offerings": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these offering oIds" }, "personas": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these persona oIds" }, "segments": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these segment oIds" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Exclude events whose segment carries these reporting tag oIds (resolved to segments; OR'd)." }, "playbooks": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these playbook oIds" }, "useCases": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these use case oIds" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these reference customer oIds" }, "competitors": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these competitor oIds" }, "alternatives": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these alternative oIds" }, "buyingTriggers": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these buying trigger oIds" }, "coreFeatures": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these core feature oIds" }, "objections": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these objection oIds" }, "proofPoints": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these proof point oIds" }, "motionTypes": { "type": "array", "items": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ] }, "description": "Exclude events matching these motion types (NET_NEW, UPSELL)" } }, "description": "Filters to EXCLUDE events matching these criteria" } } }, "pipelineFilters": { "type": "object", "properties": { "phases": { "type": "array", "items": { "type": "string", "enum": [ "prospecting", "discovery", "evaluation", "negotiation", "commitment", "closed_won", "closed_lost" ] }, "description": "Filter events linked to deals in these pipeline phases (prospecting, discovery, evaluation, negotiation, commitment, closed_won, closed_lost)" }, "stageCategories": { "type": "array", "items": { "type": "string", "enum": [ "open", "closed_won", "closed_lost", "other" ] }, "description": "Filter events linked to deals with these stage categories (open, closed_won, closed_lost, no_decision). Uses analytics-computed `stageCategory`, no stage-mapping setup required." }, "minStalledDays": { "type": "number", "description": "Only include events linked to deals stalled in their current stage for at least this many days" } } }, "dealCohort": { "type": "object", "properties": { "allOf": { "type": "array", "items": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "persona", "product", "service", "solution", "use_case", "playbook", "proof_point", "competitor", "alternative", "buying_trigger", "core_feature", "objection", "reference", "hypothesis", "segment", "target_icp", "motion_icp" ], "description": "Library entity type of the component \u2014 a simple type (persona, segment, use_case, competitor, \u2026) or a composite (target_icp / motion_icp)." }, "oId": { "type": "string", "description": "oId of the entity (or ICP) the deal must involve." } }, "required": [ "entityType", "oId" ] }, "minItems": 1, "maxItems": 8, "description": "Components a qualifying deal must ALL involve." } }, "required": [ "allOf" ], "description": "Optional deal-level scope \u2014 restricts the report's finding retrieval to deals matching this cohort (e.g. an ICP \u00d7 use-case slice from the Library Overview)." }, "actions": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "enum": [ "ADD_ENTITY", "REFINE_ENTITY", "REMOVE_ENTITY", "AGENTIC_ALL_MODIFICATIONS", "GENERATE_LEARNINGS", "GENERATE_ICP_RECOMMENDATIONS" ] }, "targetEntityTypes": { "type": "array", "items": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "Agent", "Hypothesis", "BrandVoice", "Resource" ] } } }, "required": [ "actionType", "targetEntityTypes" ] } }, "metadataFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "array_string", "array_number" ] }, "required": { "type": "boolean", "default": false } }, "required": [ "key", "type" ] } }, "userEdited": { "type": "boolean" } } }, "minEvents": { "type": "number" }, "minFindings": { "type": "number" }, "scheduleCron": { "type": "string" }, "timezone": { "type": "string" }, "nextRunAt": { "type": "string", "nullable": true, "format": "date-time" }, "configs": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "executionType": { "type": "string", "enum": [ "octave", "adhoc" ], "default": "adhoc" }, "reportId": { "type": "string" }, "prompt": { "type": "string" }, "systemPrompt": { "type": "string" }, "logicVersion": { "type": "number", "default": 1 }, "filters": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "EMAIL_INTERNAL_USE_CASE", "EMAIL_INTERNAL_PROOF_POINT", "EMAIL_INTERNAL_PAIN_POINT", "EMAIL_INTERNAL_BENEFITS_HIGHLIGHTED", "EMAIL_INTERNAL_VALUE_PROP", "EMAIL_INTERNAL_SOCIAL_PROOF", "EMAIL_INTERNAL_CALL_TO_ACTION", "EMAIL_INTERNAL_OBJECTION_HANDLING", "EMAIL_EXTERNAL_CALL_TO_ACTION", "EMAIL_EXTERNAL_OBJECTION", "EMAIL_EXTERNAL_QUESTION", "EMAIL_EXTERNAL_INTEREST_EXPRESSION", "EMAIL_EXTERNAL_FEATURE_REQUEST", "EMAIL_EXTERNAL_REQUIREMENT", "EMAIL_EXTERNAL_PRICING_FEEDBACK", "EMAIL_EXTERNAL_COMPARATIVE_STATEMENT", "EMAIL_EXTERNAL_KEY_TAKEAWAY", "EMAIL_EXTERNAL_COMPETITOR_MENTION", "EMAIL_EXTERNAL_NEXT_STEP", "EMAIL_EXTERNAL_URGENCY_INDICATOR", "EMAIL_EXTERNAL_DECISION_MAKING_SIGNAL", "EMAIL_EXTERNAL_UNIQUE_LANGUAGE_USED", "EMAIL_OVERALL_SENTIMENT", "EMAIL_TITLE_TO_PERSONA", "EMAIL_SEGMENT_DESCRIPTION", "SOCIAL_INTERNAL_USE_CASE", "SOCIAL_INTERNAL_PROOF_POINT", "SOCIAL_INTERNAL_PAIN_POINT", "SOCIAL_INTERNAL_VALUE_PROP", "SOCIAL_INTERNAL_SOCIAL_PROOF", "SOCIAL_INTERNAL_CALL_TO_ACTION", "SOCIAL_INTERNAL_BENEFITS_HIGHLIGHTED", "SOCIAL_INTERNAL_OBJECTION_HANDLING", "SOCIAL_TITLE_TO_PERSONA", "SOCIAL_SEGMENT_DESCRIPTION", "SOCIAL_PLAYBOOK_TOPICS", "SOCIAL_EXTERNAL_CALL_TO_ACTION", "SOCIAL_EXTERNAL_OBJECTION", "SOCIAL_EXTERNAL_QUESTION", "SOCIAL_EXTERNAL_INTEREST_EXPRESSION", "SOCIAL_EXTERNAL_FEATURE_REQUEST", "SOCIAL_EXTERNAL_REQUIREMENT", "SOCIAL_EXTERNAL_PRICING_FEEDBACK", "SOCIAL_EXTERNAL_COMPARATIVE_STATEMENT", "SOCIAL_EXTERNAL_KEY_TAKEAWAY", "SOCIAL_EXTERNAL_COMPETITOR_MENTION", "SOCIAL_EXTERNAL_NEXT_STEP", "SOCIAL_EXTERNAL_URGENCY_INDICATOR", "SOCIAL_EXTERNAL_DECISION_MAKING_SIGNAL", "SOCIAL_EXTERNAL_UNIQUE_LANGUAGE_USED", "SOCIAL_OVERALL_SENTIMENT", "CALL_EXTERNAL_BUSINESS_PROBLEMS", "CALL_EXTERNAL_IDEAL_SOLUTION_DESCRIPTION", "CALL_EXTERNAL_PRIMARY_GOALS", "CALL_EXTERNAL_WHY_ON_THIS_CALL", "CALL_EXTERNAL_STATUS_QUO_HOW_THEY_SOLVE_TODAY", "CALL_EXTERNAL_INDUSTRY_TRENDS", "CALL_EXTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_EXTERNAL_COMPETITORS_OF_THEIR_COMPANY", "CALL_EXTERNAL_CURRENT_TOOL_OR_SOLUTION_PROBLEMS", "CALL_EXTERNAL_OBJECTIONS", "CALL_EXTERNAL_PAIN_OR_PROBLEM_AGREEMENTS", "CALL_EXTERNAL_ROLE_OR_RESPONSIBILITIES_DESCRIPTION", "CALL_EXTERNAL_QUESTIONS_OR_CONFUSION_ABOUT_OFFERING", "CALL_EXTERNAL_CAPABILITIES_THAT_DREW_EXCITEMENT", "CALL_EXTERNAL_UNIQUE_LANGUAGE_USED", "CALL_EXTERNAL_FEATURE_REQUEST", "CALL_EXTERNAL_COMMITMENTS_MADE", "CALL_EXTERNAL_PRICING_OR_PACKAGING_FEEDBACK", "CALL_EXTERNAL_BLOCKERS_OR_DEPENDENCIES", "CALL_EXTERNAL_ABSENT_STAKEHOLDER_MENTIONS", "CALL_EXTERNAL_FRUSTRATION_OR_DISAPPOINTMENT", "CALL_EXTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_USE_CASES_BROUGHT_UP", "CALL_INTERNAL_PROOF_POINTS", "CALL_INTERNAL_REFERENCE_CUSTOMERS_OR_SOCIAL_PROOF", "CALL_INTERNAL_COMPETITORS", "CALL_INTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_INTERNAL_OBJECTION_HANDLING", "CALL_INTERNAL_VALUE_PROP_PRESENTATIONS", "CALL_INTERNAL_DIFFERENTIATED_VALUE", "CALL_INTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_COMPLEMENTARY_TOOLS_MENTIONED", "CALL_INTERNAL_COMMITMENTS_MADE", "CALL_COMPETITOR_MENTION_ORIGIN", "CALL_COMPETITOR_RELATIONSHIP_STATUS", "CALL_COMPETITOR_MENTAL_MODEL", "CALL_COMPETITOR_PROSPECT_VOICED_STRENGTH", "CALL_COMPETITOR_PROSPECT_VOICED_WEAKNESS", "CALL_COMPETITOR_OVERALL_STANCE", "CALL_COMPETITOR_HEAD_TO_HEAD_COMPARISON", "CALL_COMPETITOR_CONSIDERATION_SET_ALTERNATIVE", "CALL_COMPETITOR_COMMERCIAL_INTEL", "CALL_COMPETITOR_SWITCHING_TRIGGER_OR_BARRIER", "CALL_COMPETITOR_REP_CLAIM_REACTION", "CALL_COMPETITOR_DEAL_IMPACT", "CALL_CORE_FEATURE_MENTION_ORIGIN", "CALL_CORE_FEATURE_PROSPECT_LANGUAGE", "CALL_CORE_FEATURE_COMPREHENSION_CORRECTION", "CALL_CORE_FEATURE_PROSPECT_REACTION", "CALL_CORE_FEATURE_PROSPECT_QUESTION", "CALL_CORE_FEATURE_PROBLEM_ATTACHMENT", "CALL_CORE_FEATURE_VALUE_ARTICULATION", "CALL_CORE_FEATURE_CONCERN_OR_REQUIREMENT", "CALL_CORE_FEATURE_STATUS_QUO", "CALL_CORE_FEATURE_COMPARISON", "CALL_CORE_FEATURE_DECISION_WEIGHT", "CALL_CORE_FEATURE_USAGE_STAKEHOLDER", "RESOURCE_USE_CASES", "RESOURCE_PROOF_POINTS", "RESOURCE_REFERENCE_CUSTOMERS", "RESOURCE_COMPETITORS", "RESOURCE_OBJECTION_HANDLING", "RESOURCE_VALUE_PROPS", "RESOURCE_DIFFERENTIATED_VALUE", "RESOURCE_CORE_CAPABILITIES", "RESOURCE_SEGMENTS", "RESOURCE_INTEGRATIONS_PARTNERS", "RESOURCE_UNIQUE_LANGUAGE", "RESOURCE_PAIN_POINTS", "RESOURCE_TARGET_PERSONAS", "RESOURCE_ALTERNATIVES", "RESOURCE_BUYING_TRIGGERS", "CALL_OVERALL_SENTIMENT", "CALL_PURPOSE_CLASSIFICATION", "CALL_TITLE_TO_PERSONA", "CALL_SEGMENT_DESCRIPTION", "CRM_TITLE_TO_PERSONA", "CRM_SEGMENT_DESCRIPTION", "EVENT_SUMMARY", "BULK_IMPORT_THEMES", "BULK_LOSS_REASONS", "BULK_WIN_REASONS", "BULK_PAIN_POINTS", "BULK_USE_CASES", "BULK_COMPETITORS", "BULK_OBJECTIONS", "BULK_SEGMENTS", "BULK_PERSONAS", "ADS_INTERNAL_MESSAGING_THEME", "ADS_INTERNAL_TARGET_AUDIENCE", "ADS_INTERNAL_COMPETITIVE_POSITIONING", "ADS_INTERNAL_KEYWORD_TARGETING", "ADS_EXTERNAL_ENGAGEMENT_SIGNAL", "ADS_SEGMENT_DESCRIPTION", "ADS_MOTION_TYPE", "ADS_OFFERING_MATCH", "CALL_PROSPECT_RELATIONSHIP_TO_SELLER", "CALL_MOTION_TYPE", "CALL_OFFERING_MATCH", "EMAIL_PROSPECT_RELATIONSHIP_TO_SELLER", "EMAIL_MOTION_TYPE", "EMAIL_OFFERING_MATCH", "CRM_MOTION_TYPE", "CRM_OFFERING_MATCH", "RESOURCE_OFFERING_MATCH", "RESOURCE_TYPE_CLASSIFICATION", "CALL_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_TOPICS", "RESOURCE_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_SOURCE", "SOCIAL_PLAYBOOK_SOURCE", "CUSTOM" ] }, "value": { "type": "string", "nullable": true }, "customExtractorOId": { "type": "string", "nullable": true } }, "required": [ "type" ] } }, "events": { "type": "object", "properties": { "match": { "type": "object", "properties": { "eventCategories": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "CALL", "CRM", "RESOURCE", "REVISION", "SOCIAL", "ADS", "PRODUCT", "UNKNOWN" ] }, "description": "Filter by event categories (CALL, EMAIL, CRM)" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL_SENT", "EMAIL_REPLY_RECEIVED", "CALL_TRANSCRIPT", "DEAL_WON", "DEAL_LOST", "OPPORTUNITY_CREATED", "MEETING_BOOKED", "RESOURCE_INDEXED", "RESOURCE_REINDEXED", "PROJECT_UPDATE", "TASK_COMPLETED", "ENTITY_CREATED", "ENTITY_UPDATED", "SOCIAL_MESSAGE_SENT", "SOCIAL_MESSAGE_RECEIVED", "SOCIAL_CONNECTION_SENT", "SOCIAL_CONNECTION_ACCEPTED", "AD_SET_PUBLISHED", "AD_PERFORMANCE_SNAPSHOT", "BULK_IMPORT_SUMMARY", "PROCESSING_NOT_APPLICABLE", "PROVIDER_EVENT_TYPE_UNKNOWN", "UNKNOWN" ] }, "description": "Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.)" }, "sentiments": { "type": "array", "items": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "UNKNOWN" ] }, "description": "Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED)" }, "contactEmails": { "type": "array", "items": { "type": "string" }, "description": "Filter by participant email addresses" }, "companyDomains": { "type": "array", "items": { "type": "string" }, "description": "Filter by company domains" }, "outcomeFilters": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST", "POSITIVE_REPLY", "NEUTRAL_REPLY", "NEGATIVE_REPLY" ] }, "description": "Filter by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY)" }, "opportunityStatuses": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST" ] }, "description": "Filter by opportunity status (OPEN, WON, LOST)" }, "minDealAmount": { "type": "number", "description": "Minimum deal amount filter" }, "maxDealAmount": { "type": "number", "description": "Maximum deal amount filter" }, "offerings": { "type": "array", "items": { "type": "string" }, "description": "Filter by offering oIds" }, "personas": { "type": "array", "items": { "type": "string" }, "description": "Filter by persona oIds (events must match these personas)" }, "segments": { "type": "array", "items": { "type": "string" }, "description": "Filter by segment oIds" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by reporting tag oIds. Resolved to the segments carrying those tags; multiple tags are OR'd." }, "playbooks": { "type": "array", "items": { "type": "string" }, "description": "Filter by playbook oIds" }, "useCases": { "type": "array", "items": { "type": "string" }, "description": "Filter by use case oIds" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Filter by reference customer oIds" }, "competitors": { "type": "array", "items": { "type": "string" }, "description": "Filter by competitor oIds" }, "alternatives": { "type": "array", "items": { "type": "string" }, "description": "Filter by alternative oIds" }, "buyingTriggers": { "type": "array", "items": { "type": "string" }, "description": "Filter by buying trigger oIds" }, "coreFeatures": { "type": "array", "items": { "type": "string" }, "description": "Filter by core feature oIds" }, "objections": { "type": "array", "items": { "type": "string" }, "description": "Filter by objection oIds" }, "proofPoints": { "type": "array", "items": { "type": "string" }, "description": "Filter by proof point oIds" }, "motionTypes": { "type": "array", "items": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ] }, "description": "Filter by motion type (NET_NEW, UPSELL)" }, "callPurposes": { "type": "array", "items": { "type": "string", "enum": [ "DISCOVERY", "DEMO", "TECHNICAL_EVALUATION", "WORKING_SESSION", "NEGOTIATION_PRICING", "ONBOARDING", "CHECK_IN_SUCCESS", "QBR_RENEWAL", "EXPANSION_UPSELL", "ESCALATION_CHURN_RISK", "SUPPORT", "INTERNAL_SYNC", "OTHER" ] }, "description": "Filter calls by classified purpose (DISCOVERY, DEMO, TECHNICAL_EVALUATION, WORKING_SESSION, NEGOTIATION_PRICING, ONBOARDING, CHECK_IN_SUCCESS, QBR_RENEWAL, EXPANSION_UPSELL, ESCALATION_CHURN_RISK, SUPPORT, INTERNAL_SYNC, OTHER)" }, "unmatchedOnly": { "type": "boolean", "description": "When true, only return events that have findings with no library entity matches" } }, "description": "Filters to INCLUDE events matching these criteria" }, "exclude": { "type": "object", "properties": { "eventCategories": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "CALL", "CRM", "RESOURCE", "REVISION", "SOCIAL", "ADS", "PRODUCT", "UNKNOWN" ] }, "description": "Filter by event categories (CALL, EMAIL, CRM)" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL_SENT", "EMAIL_REPLY_RECEIVED", "CALL_TRANSCRIPT", "DEAL_WON", "DEAL_LOST", "OPPORTUNITY_CREATED", "MEETING_BOOKED", "RESOURCE_INDEXED", "RESOURCE_REINDEXED", "PROJECT_UPDATE", "TASK_COMPLETED", "ENTITY_CREATED", "ENTITY_UPDATED", "SOCIAL_MESSAGE_SENT", "SOCIAL_MESSAGE_RECEIVED", "SOCIAL_CONNECTION_SENT", "SOCIAL_CONNECTION_ACCEPTED", "AD_SET_PUBLISHED", "AD_PERFORMANCE_SNAPSHOT", "BULK_IMPORT_SUMMARY", "PROCESSING_NOT_APPLICABLE", "PROVIDER_EVENT_TYPE_UNKNOWN", "UNKNOWN" ] }, "description": "Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.)" }, "sentiments": { "type": "array", "items": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "UNKNOWN" ] }, "description": "Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED)" }, "contactEmails": { "type": "array", "items": { "type": "string" }, "description": "Filter by participant email addresses" }, "companyDomains": { "type": "array", "items": { "type": "string" }, "description": "Filter by company domains" }, "outcomeFilters": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST", "POSITIVE_REPLY", "NEUTRAL_REPLY", "NEGATIVE_REPLY" ] }, "description": "Exclude by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY)" }, "opportunityStatuses": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST" ] }, "description": "Exclude by opportunity status (OPEN, WON, LOST)" }, "minDealAmount": { "type": "number", "description": "Minimum deal amount filter" }, "maxDealAmount": { "type": "number", "description": "Maximum deal amount filter" }, "offerings": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these offering oIds" }, "personas": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these persona oIds" }, "segments": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these segment oIds" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Exclude events whose segment carries these reporting tag oIds (resolved to segments; OR'd)." }, "playbooks": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these playbook oIds" }, "useCases": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these use case oIds" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these reference customer oIds" }, "competitors": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these competitor oIds" }, "alternatives": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these alternative oIds" }, "buyingTriggers": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these buying trigger oIds" }, "coreFeatures": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these core feature oIds" }, "objections": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these objection oIds" }, "proofPoints": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these proof point oIds" }, "motionTypes": { "type": "array", "items": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ] }, "description": "Exclude events matching these motion types (NET_NEW, UPSELL)" } }, "description": "Filters to EXCLUDE events matching these criteria" } } }, "pipelineFilters": { "type": "object", "properties": { "phases": { "type": "array", "items": { "type": "string", "enum": [ "prospecting", "discovery", "evaluation", "negotiation", "commitment", "closed_won", "closed_lost" ] }, "description": "Filter events linked to deals in these pipeline phases (prospecting, discovery, evaluation, negotiation, commitment, closed_won, closed_lost)" }, "stageCategories": { "type": "array", "items": { "type": "string", "enum": [ "open", "closed_won", "closed_lost", "other" ] }, "description": "Filter events linked to deals with these stage categories (open, closed_won, closed_lost, no_decision). Uses analytics-computed `stageCategory`, no stage-mapping setup required." }, "minStalledDays": { "type": "number", "description": "Only include events linked to deals stalled in their current stage for at least this many days" } } }, "dealCohort": { "type": "object", "properties": { "allOf": { "type": "array", "items": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "persona", "product", "service", "solution", "use_case", "playbook", "proof_point", "competitor", "alternative", "buying_trigger", "core_feature", "objection", "reference", "hypothesis", "segment", "target_icp", "motion_icp" ], "description": "Library entity type of the component \u2014 a simple type (persona, segment, use_case, competitor, \u2026) or a composite (target_icp / motion_icp)." }, "oId": { "type": "string", "description": "oId of the entity (or ICP) the deal must involve." } }, "required": [ "entityType", "oId" ] }, "minItems": 1, "maxItems": 8, "description": "Components a qualifying deal must ALL involve." } }, "required": [ "allOf" ], "description": "Optional deal-level scope \u2014 restricts the report's finding retrieval to deals matching this cohort (e.g. an ICP \u00d7 use-case slice from the Library Overview)." }, "actions": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "enum": [ "ADD_ENTITY", "REFINE_ENTITY", "REMOVE_ENTITY", "AGENTIC_ALL_MODIFICATIONS", "GENERATE_LEARNINGS", "GENERATE_ICP_RECOMMENDATIONS" ] }, "targetEntityTypes": { "type": "array", "items": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "Agent", "Hypothesis", "BrandVoice", "Resource" ] } } }, "required": [ "actionType", "targetEntityTypes" ] } }, "metadataFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "array_string", "array_number" ] }, "required": { "type": "boolean", "default": false } }, "required": [ "key", "type" ] } }, "userEdited": { "type": "boolean" } }, "required": [ "findings" ] }, "groupId": { "type": "string" }, "isActive": { "type": "boolean" }, "minEvents": { "type": "number" }, "minFindings": { "type": "number" }, "lastSuccessfulEndAt": { "type": "string", "nullable": true, "format": "date-time" }, "consecutiveFailures": { "type": "number" }, "notificationSettings": { "type": "object", "properties": { "email": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "addresses": { "type": "array", "items": { "type": "string", "format": "email" } } }, "required": [ "enabled", "addresses" ] }, "slack": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "enabled", "channels" ] } } } }, "required": [ "oId", "title", "filters", "isActive" ] } }, "notificationSettings": { "type": "object", "properties": { "email": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "addresses": { "type": "array", "items": { "type": "string", "format": "email" } } }, "required": [ "enabled", "addresses" ] }, "slack": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "enabled", "channels" ] } } } }, "required": [ "oId", "title", "type", "aggregationLevel" ] }, "ReportConfig": { "type": "object", "properties": { "oId": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "executionType": { "type": "string", "enum": [ "octave", "adhoc" ], "default": "adhoc" }, "reportId": { "type": "string" }, "prompt": { "type": "string" }, "systemPrompt": { "type": "string" }, "logicVersion": { "type": "number", "default": 1 }, "filters": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "EMAIL_INTERNAL_USE_CASE", "EMAIL_INTERNAL_PROOF_POINT", "EMAIL_INTERNAL_PAIN_POINT", "EMAIL_INTERNAL_BENEFITS_HIGHLIGHTED", "EMAIL_INTERNAL_VALUE_PROP", "EMAIL_INTERNAL_SOCIAL_PROOF", "EMAIL_INTERNAL_CALL_TO_ACTION", "EMAIL_INTERNAL_OBJECTION_HANDLING", "EMAIL_EXTERNAL_CALL_TO_ACTION", "EMAIL_EXTERNAL_OBJECTION", "EMAIL_EXTERNAL_QUESTION", "EMAIL_EXTERNAL_INTEREST_EXPRESSION", "EMAIL_EXTERNAL_FEATURE_REQUEST", "EMAIL_EXTERNAL_REQUIREMENT", "EMAIL_EXTERNAL_PRICING_FEEDBACK", "EMAIL_EXTERNAL_COMPARATIVE_STATEMENT", "EMAIL_EXTERNAL_KEY_TAKEAWAY", "EMAIL_EXTERNAL_COMPETITOR_MENTION", "EMAIL_EXTERNAL_NEXT_STEP", "EMAIL_EXTERNAL_URGENCY_INDICATOR", "EMAIL_EXTERNAL_DECISION_MAKING_SIGNAL", "EMAIL_EXTERNAL_UNIQUE_LANGUAGE_USED", "EMAIL_OVERALL_SENTIMENT", "EMAIL_TITLE_TO_PERSONA", "EMAIL_SEGMENT_DESCRIPTION", "SOCIAL_INTERNAL_USE_CASE", "SOCIAL_INTERNAL_PROOF_POINT", "SOCIAL_INTERNAL_PAIN_POINT", "SOCIAL_INTERNAL_VALUE_PROP", "SOCIAL_INTERNAL_SOCIAL_PROOF", "SOCIAL_INTERNAL_CALL_TO_ACTION", "SOCIAL_INTERNAL_BENEFITS_HIGHLIGHTED", "SOCIAL_INTERNAL_OBJECTION_HANDLING", "SOCIAL_TITLE_TO_PERSONA", "SOCIAL_SEGMENT_DESCRIPTION", "SOCIAL_PLAYBOOK_TOPICS", "SOCIAL_EXTERNAL_CALL_TO_ACTION", "SOCIAL_EXTERNAL_OBJECTION", "SOCIAL_EXTERNAL_QUESTION", "SOCIAL_EXTERNAL_INTEREST_EXPRESSION", "SOCIAL_EXTERNAL_FEATURE_REQUEST", "SOCIAL_EXTERNAL_REQUIREMENT", "SOCIAL_EXTERNAL_PRICING_FEEDBACK", "SOCIAL_EXTERNAL_COMPARATIVE_STATEMENT", "SOCIAL_EXTERNAL_KEY_TAKEAWAY", "SOCIAL_EXTERNAL_COMPETITOR_MENTION", "SOCIAL_EXTERNAL_NEXT_STEP", "SOCIAL_EXTERNAL_URGENCY_INDICATOR", "SOCIAL_EXTERNAL_DECISION_MAKING_SIGNAL", "SOCIAL_EXTERNAL_UNIQUE_LANGUAGE_USED", "SOCIAL_OVERALL_SENTIMENT", "CALL_EXTERNAL_BUSINESS_PROBLEMS", "CALL_EXTERNAL_IDEAL_SOLUTION_DESCRIPTION", "CALL_EXTERNAL_PRIMARY_GOALS", "CALL_EXTERNAL_WHY_ON_THIS_CALL", "CALL_EXTERNAL_STATUS_QUO_HOW_THEY_SOLVE_TODAY", "CALL_EXTERNAL_INDUSTRY_TRENDS", "CALL_EXTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_EXTERNAL_COMPETITORS_OF_THEIR_COMPANY", "CALL_EXTERNAL_CURRENT_TOOL_OR_SOLUTION_PROBLEMS", "CALL_EXTERNAL_OBJECTIONS", "CALL_EXTERNAL_PAIN_OR_PROBLEM_AGREEMENTS", "CALL_EXTERNAL_ROLE_OR_RESPONSIBILITIES_DESCRIPTION", "CALL_EXTERNAL_QUESTIONS_OR_CONFUSION_ABOUT_OFFERING", "CALL_EXTERNAL_CAPABILITIES_THAT_DREW_EXCITEMENT", "CALL_EXTERNAL_UNIQUE_LANGUAGE_USED", "CALL_EXTERNAL_FEATURE_REQUEST", "CALL_EXTERNAL_COMMITMENTS_MADE", "CALL_EXTERNAL_PRICING_OR_PACKAGING_FEEDBACK", "CALL_EXTERNAL_BLOCKERS_OR_DEPENDENCIES", "CALL_EXTERNAL_ABSENT_STAKEHOLDER_MENTIONS", "CALL_EXTERNAL_FRUSTRATION_OR_DISAPPOINTMENT", "CALL_EXTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_USE_CASES_BROUGHT_UP", "CALL_INTERNAL_PROOF_POINTS", "CALL_INTERNAL_REFERENCE_CUSTOMERS_OR_SOCIAL_PROOF", "CALL_INTERNAL_COMPETITORS", "CALL_INTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_INTERNAL_OBJECTION_HANDLING", "CALL_INTERNAL_VALUE_PROP_PRESENTATIONS", "CALL_INTERNAL_DIFFERENTIATED_VALUE", "CALL_INTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_COMPLEMENTARY_TOOLS_MENTIONED", "CALL_INTERNAL_COMMITMENTS_MADE", "CALL_COMPETITOR_MENTION_ORIGIN", "CALL_COMPETITOR_RELATIONSHIP_STATUS", "CALL_COMPETITOR_MENTAL_MODEL", "CALL_COMPETITOR_PROSPECT_VOICED_STRENGTH", "CALL_COMPETITOR_PROSPECT_VOICED_WEAKNESS", "CALL_COMPETITOR_OVERALL_STANCE", "CALL_COMPETITOR_HEAD_TO_HEAD_COMPARISON", "CALL_COMPETITOR_CONSIDERATION_SET_ALTERNATIVE", "CALL_COMPETITOR_COMMERCIAL_INTEL", "CALL_COMPETITOR_SWITCHING_TRIGGER_OR_BARRIER", "CALL_COMPETITOR_REP_CLAIM_REACTION", "CALL_COMPETITOR_DEAL_IMPACT", "CALL_CORE_FEATURE_MENTION_ORIGIN", "CALL_CORE_FEATURE_PROSPECT_LANGUAGE", "CALL_CORE_FEATURE_COMPREHENSION_CORRECTION", "CALL_CORE_FEATURE_PROSPECT_REACTION", "CALL_CORE_FEATURE_PROSPECT_QUESTION", "CALL_CORE_FEATURE_PROBLEM_ATTACHMENT", "CALL_CORE_FEATURE_VALUE_ARTICULATION", "CALL_CORE_FEATURE_CONCERN_OR_REQUIREMENT", "CALL_CORE_FEATURE_STATUS_QUO", "CALL_CORE_FEATURE_COMPARISON", "CALL_CORE_FEATURE_DECISION_WEIGHT", "CALL_CORE_FEATURE_USAGE_STAKEHOLDER", "RESOURCE_USE_CASES", "RESOURCE_PROOF_POINTS", "RESOURCE_REFERENCE_CUSTOMERS", "RESOURCE_COMPETITORS", "RESOURCE_OBJECTION_HANDLING", "RESOURCE_VALUE_PROPS", "RESOURCE_DIFFERENTIATED_VALUE", "RESOURCE_CORE_CAPABILITIES", "RESOURCE_SEGMENTS", "RESOURCE_INTEGRATIONS_PARTNERS", "RESOURCE_UNIQUE_LANGUAGE", "RESOURCE_PAIN_POINTS", "RESOURCE_TARGET_PERSONAS", "RESOURCE_ALTERNATIVES", "RESOURCE_BUYING_TRIGGERS", "CALL_OVERALL_SENTIMENT", "CALL_PURPOSE_CLASSIFICATION", "CALL_TITLE_TO_PERSONA", "CALL_SEGMENT_DESCRIPTION", "CRM_TITLE_TO_PERSONA", "CRM_SEGMENT_DESCRIPTION", "EVENT_SUMMARY", "BULK_IMPORT_THEMES", "BULK_LOSS_REASONS", "BULK_WIN_REASONS", "BULK_PAIN_POINTS", "BULK_USE_CASES", "BULK_COMPETITORS", "BULK_OBJECTIONS", "BULK_SEGMENTS", "BULK_PERSONAS", "ADS_INTERNAL_MESSAGING_THEME", "ADS_INTERNAL_TARGET_AUDIENCE", "ADS_INTERNAL_COMPETITIVE_POSITIONING", "ADS_INTERNAL_KEYWORD_TARGETING", "ADS_EXTERNAL_ENGAGEMENT_SIGNAL", "ADS_SEGMENT_DESCRIPTION", "ADS_MOTION_TYPE", "ADS_OFFERING_MATCH", "CALL_PROSPECT_RELATIONSHIP_TO_SELLER", "CALL_MOTION_TYPE", "CALL_OFFERING_MATCH", "EMAIL_PROSPECT_RELATIONSHIP_TO_SELLER", "EMAIL_MOTION_TYPE", "EMAIL_OFFERING_MATCH", "CRM_MOTION_TYPE", "CRM_OFFERING_MATCH", "RESOURCE_OFFERING_MATCH", "RESOURCE_TYPE_CLASSIFICATION", "CALL_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_TOPICS", "RESOURCE_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_SOURCE", "SOCIAL_PLAYBOOK_SOURCE", "CUSTOM" ] }, "value": { "type": "string", "nullable": true }, "customExtractorOId": { "type": "string", "nullable": true } }, "required": [ "type" ] } }, "events": { "type": "object", "properties": { "match": { "type": "object", "properties": { "eventCategories": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "CALL", "CRM", "RESOURCE", "REVISION", "SOCIAL", "ADS", "PRODUCT", "UNKNOWN" ] }, "description": "Filter by event categories (CALL, EMAIL, CRM)" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL_SENT", "EMAIL_REPLY_RECEIVED", "CALL_TRANSCRIPT", "DEAL_WON", "DEAL_LOST", "OPPORTUNITY_CREATED", "MEETING_BOOKED", "RESOURCE_INDEXED", "RESOURCE_REINDEXED", "PROJECT_UPDATE", "TASK_COMPLETED", "ENTITY_CREATED", "ENTITY_UPDATED", "SOCIAL_MESSAGE_SENT", "SOCIAL_MESSAGE_RECEIVED", "SOCIAL_CONNECTION_SENT", "SOCIAL_CONNECTION_ACCEPTED", "AD_SET_PUBLISHED", "AD_PERFORMANCE_SNAPSHOT", "BULK_IMPORT_SUMMARY", "PROCESSING_NOT_APPLICABLE", "PROVIDER_EVENT_TYPE_UNKNOWN", "UNKNOWN" ] }, "description": "Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.)" }, "sentiments": { "type": "array", "items": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "UNKNOWN" ] }, "description": "Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED)" }, "contactEmails": { "type": "array", "items": { "type": "string" }, "description": "Filter by participant email addresses" }, "companyDomains": { "type": "array", "items": { "type": "string" }, "description": "Filter by company domains" }, "outcomeFilters": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST", "POSITIVE_REPLY", "NEUTRAL_REPLY", "NEGATIVE_REPLY" ] }, "description": "Filter by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY)" }, "opportunityStatuses": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST" ] }, "description": "Filter by opportunity status (OPEN, WON, LOST)" }, "minDealAmount": { "type": "number", "description": "Minimum deal amount filter" }, "maxDealAmount": { "type": "number", "description": "Maximum deal amount filter" }, "offerings": { "type": "array", "items": { "type": "string" }, "description": "Filter by offering oIds" }, "personas": { "type": "array", "items": { "type": "string" }, "description": "Filter by persona oIds (events must match these personas)" }, "segments": { "type": "array", "items": { "type": "string" }, "description": "Filter by segment oIds" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Filter by reporting tag oIds. Resolved to the segments carrying those tags; multiple tags are OR'd." }, "playbooks": { "type": "array", "items": { "type": "string" }, "description": "Filter by playbook oIds" }, "useCases": { "type": "array", "items": { "type": "string" }, "description": "Filter by use case oIds" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Filter by reference customer oIds" }, "competitors": { "type": "array", "items": { "type": "string" }, "description": "Filter by competitor oIds" }, "alternatives": { "type": "array", "items": { "type": "string" }, "description": "Filter by alternative oIds" }, "buyingTriggers": { "type": "array", "items": { "type": "string" }, "description": "Filter by buying trigger oIds" }, "coreFeatures": { "type": "array", "items": { "type": "string" }, "description": "Filter by core feature oIds" }, "objections": { "type": "array", "items": { "type": "string" }, "description": "Filter by objection oIds" }, "proofPoints": { "type": "array", "items": { "type": "string" }, "description": "Filter by proof point oIds" }, "motionTypes": { "type": "array", "items": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ] }, "description": "Filter by motion type (NET_NEW, UPSELL)" }, "callPurposes": { "type": "array", "items": { "type": "string", "enum": [ "DISCOVERY", "DEMO", "TECHNICAL_EVALUATION", "WORKING_SESSION", "NEGOTIATION_PRICING", "ONBOARDING", "CHECK_IN_SUCCESS", "QBR_RENEWAL", "EXPANSION_UPSELL", "ESCALATION_CHURN_RISK", "SUPPORT", "INTERNAL_SYNC", "OTHER" ] }, "description": "Filter calls by classified purpose (DISCOVERY, DEMO, TECHNICAL_EVALUATION, WORKING_SESSION, NEGOTIATION_PRICING, ONBOARDING, CHECK_IN_SUCCESS, QBR_RENEWAL, EXPANSION_UPSELL, ESCALATION_CHURN_RISK, SUPPORT, INTERNAL_SYNC, OTHER)" }, "unmatchedOnly": { "type": "boolean", "description": "When true, only return events that have findings with no library entity matches" } }, "description": "Filters to INCLUDE events matching these criteria" }, "exclude": { "type": "object", "properties": { "eventCategories": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "CALL", "CRM", "RESOURCE", "REVISION", "SOCIAL", "ADS", "PRODUCT", "UNKNOWN" ] }, "description": "Filter by event categories (CALL, EMAIL, CRM)" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL_SENT", "EMAIL_REPLY_RECEIVED", "CALL_TRANSCRIPT", "DEAL_WON", "DEAL_LOST", "OPPORTUNITY_CREATED", "MEETING_BOOKED", "RESOURCE_INDEXED", "RESOURCE_REINDEXED", "PROJECT_UPDATE", "TASK_COMPLETED", "ENTITY_CREATED", "ENTITY_UPDATED", "SOCIAL_MESSAGE_SENT", "SOCIAL_MESSAGE_RECEIVED", "SOCIAL_CONNECTION_SENT", "SOCIAL_CONNECTION_ACCEPTED", "AD_SET_PUBLISHED", "AD_PERFORMANCE_SNAPSHOT", "BULK_IMPORT_SUMMARY", "PROCESSING_NOT_APPLICABLE", "PROVIDER_EVENT_TYPE_UNKNOWN", "UNKNOWN" ] }, "description": "Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.)" }, "sentiments": { "type": "array", "items": { "type": "string", "enum": [ "POSITIVE", "NEUTRAL", "NEGATIVE", "UNKNOWN" ] }, "description": "Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED)" }, "contactEmails": { "type": "array", "items": { "type": "string" }, "description": "Filter by participant email addresses" }, "companyDomains": { "type": "array", "items": { "type": "string" }, "description": "Filter by company domains" }, "outcomeFilters": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST", "POSITIVE_REPLY", "NEUTRAL_REPLY", "NEGATIVE_REPLY" ] }, "description": "Exclude by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY)" }, "opportunityStatuses": { "type": "array", "items": { "type": "string", "enum": [ "OPEN", "WON", "LOST" ] }, "description": "Exclude by opportunity status (OPEN, WON, LOST)" }, "minDealAmount": { "type": "number", "description": "Minimum deal amount filter" }, "maxDealAmount": { "type": "number", "description": "Maximum deal amount filter" }, "offerings": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these offering oIds" }, "personas": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these persona oIds" }, "segments": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these segment oIds" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Exclude events whose segment carries these reporting tag oIds (resolved to segments; OR'd)." }, "playbooks": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these playbook oIds" }, "useCases": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these use case oIds" }, "references": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these reference customer oIds" }, "competitors": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these competitor oIds" }, "alternatives": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these alternative oIds" }, "buyingTriggers": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these buying trigger oIds" }, "coreFeatures": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these core feature oIds" }, "objections": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these objection oIds" }, "proofPoints": { "type": "array", "items": { "type": "string" }, "description": "Exclude events matching these proof point oIds" }, "motionTypes": { "type": "array", "items": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ] }, "description": "Exclude events matching these motion types (NET_NEW, UPSELL)" } }, "description": "Filters to EXCLUDE events matching these criteria" } } }, "pipelineFilters": { "type": "object", "properties": { "phases": { "type": "array", "items": { "type": "string", "enum": [ "prospecting", "discovery", "evaluation", "negotiation", "commitment", "closed_won", "closed_lost" ] }, "description": "Filter events linked to deals in these pipeline phases (prospecting, discovery, evaluation, negotiation, commitment, closed_won, closed_lost)" }, "stageCategories": { "type": "array", "items": { "type": "string", "enum": [ "open", "closed_won", "closed_lost", "other" ] }, "description": "Filter events linked to deals with these stage categories (open, closed_won, closed_lost, no_decision). Uses analytics-computed `stageCategory`, no stage-mapping setup required." }, "minStalledDays": { "type": "number", "description": "Only include events linked to deals stalled in their current stage for at least this many days" } } }, "dealCohort": { "type": "object", "properties": { "allOf": { "type": "array", "items": { "type": "object", "properties": { "entityType": { "type": "string", "enum": [ "persona", "product", "service", "solution", "use_case", "playbook", "proof_point", "competitor", "alternative", "buying_trigger", "core_feature", "objection", "reference", "hypothesis", "segment", "target_icp", "motion_icp" ], "description": "Library entity type of the component \u2014 a simple type (persona, segment, use_case, competitor, \u2026) or a composite (target_icp / motion_icp)." }, "oId": { "type": "string", "description": "oId of the entity (or ICP) the deal must involve." } }, "required": [ "entityType", "oId" ] }, "minItems": 1, "maxItems": 8, "description": "Components a qualifying deal must ALL involve." } }, "required": [ "allOf" ], "description": "Optional deal-level scope \u2014 restricts the report's finding retrieval to deals matching this cohort (e.g. an ICP \u00d7 use-case slice from the Library Overview)." }, "actions": { "type": "array", "items": { "type": "object", "properties": { "actionType": { "type": "string", "enum": [ "ADD_ENTITY", "REFINE_ENTITY", "REMOVE_ENTITY", "AGENTIC_ALL_MODIFICATIONS", "GENERATE_LEARNINGS", "GENERATE_ICP_RECOMMENDATIONS" ] }, "targetEntityTypes": { "type": "array", "items": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "Agent", "Hypothesis", "BrandVoice", "Resource" ] } } }, "required": [ "actionType", "targetEntityTypes" ] } }, "metadataFields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "array_string", "array_number" ] }, "required": { "type": "boolean", "default": false } }, "required": [ "key", "type" ] } }, "userEdited": { "type": "boolean" } }, "required": [ "findings" ] }, "groupId": { "type": "string" }, "isActive": { "type": "boolean" }, "minEvents": { "type": "number" }, "minFindings": { "type": "number" }, "lastSuccessfulEndAt": { "type": "string", "nullable": true, "format": "date-time" }, "consecutiveFailures": { "type": "number" }, "notificationSettings": { "type": "object", "properties": { "email": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "addresses": { "type": "array", "items": { "type": "string", "format": "email" } } }, "required": [ "enabled", "addresses" ] }, "slack": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "enabled", "channels" ] } } } }, "required": [ "oId", "title", "filters", "isActive" ] }, "ReportRunSummary": { "type": "object", "properties": { "oId": { "type": "string", "description": "Report run oId" }, "status": { "type": "string", "enum": [ "started", "succeeded", "failed", "skipped", "analyzing" ], "description": "Run status" }, "title": { "type": "string", "nullable": true, "description": "AI-generated report title" }, "summary": { "type": "string", "nullable": true, "description": "AI-generated summary" }, "windowStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Report window start" }, "windowEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Report window end" } }, "required": [ "oId", "status", "title", "summary" ] }, "ReportRunDetail": { "type": "object", "properties": { "oId": { "type": "string", "description": "Report run oId" }, "status": { "type": "string", "enum": [ "started", "succeeded", "failed", "skipped", "analyzing" ], "description": "Run status" }, "title": { "type": "string", "nullable": true, "description": "AI-generated report title" }, "summary": { "type": "string", "nullable": true, "description": "AI-generated summary" }, "windowStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Report window start" }, "windowEnd": { "type": "string", "nullable": true, "format": "date-time", "description": "Report window end" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/ReportSection" }, "description": "Report sections" }, "comparisonWithPrevious": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "Comparison with previous report run" } }, "required": [ "oId", "status", "title", "summary", "sections", "comparisonWithPrevious" ] }, "ReportSection": { "type": "object", "properties": { "oId": { "type": "string", "description": "Section oId" }, "topic": { "type": "string", "nullable": true, "description": "Section topic/theme" }, "details": { "type": "string", "description": "Narrative analysis for this section" }, "sectionOrder": { "type": "number", "description": "Position within the report (0-indexed)" }, "evidenceCount": { "type": "number", "description": "Number of supporting findings" } }, "required": [ "oId", "topic", "details", "sectionOrder", "evidenceCount" ] }, "WorkspaceBaseline": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "periodType": { "type": "string", "enum": [ "week", "month", "quarter" ] }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "totalClosedDeals": { "type": "integer" }, "totalWonDeals": { "type": "integer" }, "totalLostDeals": { "type": "integer" }, "totalOpenDealCount": { "type": "integer" }, "totalWonDealAmount": { "type": "string" }, "totalLostDealAmount": { "type": "string" }, "totalOpenDealAmount": { "type": "string" }, "baselineWinRate": { "type": "number", "nullable": true }, "avgDealSize": { "type": "string", "nullable": true }, "avgDealCycleDays": { "type": "number", "nullable": true }, "totalFindingsInPeriod": { "type": "integer" }, "lastComputedAt": { "type": "string" } }, "required": [ "oId", "periodType", "periodStart", "periodEnd", "totalClosedDeals", "totalWonDeals", "totalLostDeals", "totalOpenDealCount", "totalWonDealAmount", "totalLostDealAmount", "totalOpenDealAmount", "baselineWinRate", "avgDealSize", "avgDealCycleDays", "totalFindingsInPeriod", "lastComputedAt" ] }, "EntityStats": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "description": "Stats row oId" }, "entityType": { "type": "string", "enum": [ "persona", "product", "service", "solution", "use_case", "playbook", "proof_point", "competitor", "alternative", "buying_trigger", "core_feature", "objection", "reference", "hypothesis", "segment", "target_icp", "motion_icp" ] }, "entityOId": { "type": "string" }, "periodType": { "type": "string", "enum": [ "week", "month", "quarter" ] }, "periodStart": { "type": "string" }, "periodEnd": { "type": "string" }, "wonDealCount": { "type": "integer" }, "lostDealCount": { "type": "integer" }, "noDecisionDealCount": { "type": "integer" }, "openDealCount": { "type": "integer" }, "wonDealTotalAmount": { "type": "string" }, "lostDealTotalAmount": { "type": "string" }, "totalFindingCount": { "type": "integer" }, "uniqueEventCount": { "type": "integer" }, "uniqueCompanyCount": { "type": "integer" }, "uniqueContactCount": { "type": "integer" }, "winRate": { "type": "number", "nullable": true }, "relativeWinRate": { "type": "number", "nullable": true }, "liftScore": { "type": "number", "nullable": true }, "winRateDelta": { "type": "number", "nullable": true }, "isUbiquitous": { "type": "boolean" }, "dealsWherePresent": { "type": "integer" }, "dealsWhereAbsent": { "type": "integer" }, "lastComputedAt": { "type": "string" } }, "required": [ "oId", "entityType", "entityOId", "periodType", "periodStart", "periodEnd", "wonDealCount", "lostDealCount", "noDecisionDealCount", "openDealCount", "wonDealTotalAmount", "lostDealTotalAmount", "totalFindingCount", "uniqueEventCount", "uniqueCompanyCount", "uniqueContactCount", "winRate", "relativeWinRate", "liftScore", "winRateDelta", "isUbiquitous", "dealsWherePresent", "dealsWhereAbsent", "lastComputedAt" ] }, "EntityStatsWithName": { "allOf": [ { "$ref": "#/components/schemas/EntityStats" }, { "type": "object", "properties": { "entityName": { "type": "string" } }, "required": [ "entityName" ] } ] }, "LibraryHealthRow": { "type": "object", "properties": { "entityType": { "type": "string" }, "entityCount": { "type": "integer" }, "totalFindings": { "type": "integer" }, "callFindings": { "type": "integer" }, "emailFindings": { "type": "integer" }, "wonDealCount": { "type": "integer" }, "lostDealCount": { "type": "integer" }, "totalDeals": { "type": "integer" } }, "required": [ "entityType", "entityCount", "totalFindings", "callFindings", "emailFindings", "wonDealCount", "lostDealCount", "totalDeals" ] }, "SuggestionListItem": { "type": "object", "properties": { "oId": { "type": "string", "description": "The suggestion's oId (use with get/accept/reject/update)." }, "status": { "type": "string", "enum": [ "draft", "pending", "accepted", "rejected", "dismissed", "expired" ], "description": "Lifecycle status. 'pending' is awaiting review and is the only status that can be accepted or rejected. 'accepted' and 'rejected' are reviewer decisions. 'dismissed' was cleared without a decision. 'expired' means the review window ran out before anyone looked \u2014 it is not a judgement on the suggestion. 'draft' is internal." }, "changeType": { "type": "string", "enum": [ "add", "refine" ], "description": "Friendly framing of the change: 'add' creates a brand new library entity; 'refine' changes an existing one.", "example": "add" }, "suggestionType": { "type": "string", "enum": [ "create_entity", "update_entity", "generate_entity", "refine_entity", "link_entities" ], "description": "The raw underlying suggestion type." }, "targetEntityType": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "Agent", "Hypothesis", "BrandVoice", "Resource" ], "description": "The library entity type being added or refined." }, "targetEntityOId": { "type": "string", "nullable": true, "description": "oId of the entity being refined (null for 'add')." }, "name": { "type": "string", "description": "Name of the entity to add or the entity being refined (empty string when none)." }, "description": { "type": "string", "nullable": true, "description": "Description of the entity to add ('add' suggestions)." }, "message": { "type": "string", "nullable": true, "description": "The refinement instruction message ('refine' suggestions)." }, "summaryMessage": { "type": "string", "nullable": true, "description": "LLM-generated summary of what was refined ('refine')." }, "reasoning": { "type": "string", "description": "Why this suggestion was generated." }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the suggestion was created (ISO 8601)." } }, "required": [ "oId", "status", "changeType", "suggestionType", "targetEntityType", "targetEntityOId", "name", "description", "message", "summaryMessage", "reasoning", "createdAt" ] }, "SuggestionDetail": { "type": "object", "properties": { "oId": { "type": "string", "description": "The suggestion's oId." }, "status": { "type": "string", "enum": [ "draft", "pending", "accepted", "rejected", "dismissed", "expired" ], "description": "Lifecycle status. 'pending' is awaiting review and is the only status that can be accepted or rejected. 'accepted' and 'rejected' are reviewer decisions. 'dismissed' was cleared without a decision. 'expired' means the review window ran out before anyone looked \u2014 it is not a judgement on the suggestion. 'draft' is internal." }, "changeType": { "type": "string", "enum": [ "add", "refine" ], "description": "Friendly framing of the change: 'add' creates a brand new library entity; 'refine' changes an existing one.", "example": "add" }, "suggestionType": { "type": "string", "enum": [ "create_entity", "update_entity", "generate_entity", "refine_entity", "link_entities" ], "description": "The raw underlying suggestion type." }, "targetEntityType": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "Agent", "Hypothesis", "BrandVoice", "Resource" ], "description": "The library entity type being added or refined." }, "targetEntityOId": { "type": "string", "nullable": true, "description": "oId of the entity being refined (null for 'add')." }, "name": { "type": "string", "nullable": true, "description": "Name of the entity to add or refine." }, "message": { "type": "string", "nullable": true, "description": "Refinement instruction message ('refine' suggestions)." }, "summaryMessage": { "type": "string", "nullable": true, "description": "LLM-generated summary of what was refined ('refine')." }, "attributes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "For 'refine' suggestions: the entity attribute names the refinement changes (e.g. ['competitorWeaknesses']). Null when the suggestion isn't attribute-scoped." }, "reasoning": { "type": "string", "description": "Why this suggestion was generated." }, "confidence": { "type": "number", "nullable": true, "description": "Model confidence in the suggestion, when scored." }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the suggestion was created (ISO 8601)." }, "preview": { "nullable": true, "description": "For 'add': the full proposed new entity. For 'refine': the entity as it would look after the change is applied. Null if not generated (omitted preview, or generation failed)." }, "currentEntity": { "nullable": true, "description": "For 'refine': the current entity before the change, to diff against `preview`. Null for 'add'." }, "docUpdate": { "type": "object", "nullable": true, "properties": { "insight": { "type": "string", "description": "What changed in the field." }, "recommendedAction": { "type": "string", "description": "The update the doc owner should make." }, "proposedUpstreamEdit": { "type": "string", "description": "Ready-to-apply draft of the edit; may be empty." }, "resourceName": { "type": "string", "nullable": true, "description": "The source doc's name." }, "sourceUrl": { "type": "string", "nullable": true, "description": "External deep link to the source doc (Drive/Notion/Linear URL, or the page URL for website resources)." }, "primaryEntityType": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "Agent", "Hypothesis", "BrandVoice", "Resource" ], "description": "The drifted library entity's type." }, "primaryEntityOId": { "type": "string", "description": "The drifted library entity \u2014 resolvable via entity/get." }, "provenance": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "entityOId": { "type": "string" }, "entityType": { "type": "string" }, "entityName": { "type": "string", "nullable": true }, "rationale": { "type": "string", "nullable": true }, "changes": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "suggestion", "user", "apiKey", "mcp", "unknown" ] }, "at": { "type": "string" }, "summary": { "type": "string" }, "suggestionOId": { "type": "string", "nullable": true }, "findingCount": { "type": "number", "nullable": true }, "findings": { "type": "array", "items": { "type": "object", "properties": { "findingOId": { "type": "string" }, "actor": { "type": "string", "nullable": true }, "actorTitle": { "type": "string", "nullable": true }, "companyName": { "type": "string", "nullable": true }, "companyDomain": { "type": "string", "nullable": true }, "providerName": { "type": "string", "nullable": true }, "extractionType": { "type": "string" }, "snippetText": { "type": "string" }, "text": { "type": "string" }, "occurredAt": { "type": "string" } }, "required": [ "findingOId", "extractionType", "snippetText", "text", "occurredAt" ] } } }, "required": [ "source", "at", "summary", "findings" ] } } }, "required": [ "entityOId", "entityType", "changes" ] }, "description": "The upstream-change trail behind this doc update: what changed on the triggering entities (accepted suggestions / manual edits, with dates and channels) and the curated findings behind those changes. Null on rows created before provenance capture." }, "editHunks": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "anchor": { "type": "string" }, "replacement": { "type": "string" }, "kind": { "type": "string", "enum": [ "replace", "insert_after", "delete" ] } }, "required": [ "anchor", "replacement", "kind" ] }, "description": "Anchor-validated before/after edit hunks (each anchor is a verbatim excerpt of the doc at check time). Null on rows created before hunk capture. For live-doc staleness checks, use includeDiff=true and read diffChunks instead." } }, "required": [ "insight", "recommendedAction", "proposedUpstreamEdit", "resourceName", "sourceUrl", "primaryEntityType", "primaryEntityOId", "provenance", "editHunks" ], "description": "For Resource-target (doc-update) suggestions: the structured drift proposal an external agent needs to apply the edit upstream. `targetEntityOId` is the doc itself. Null for library-entity suggestions, and for Resource suggestions whose payload predates the drift pipeline \u2014 check targetEntityType to tell shapes apart." }, "evidence": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/SuggestionEvidenceItem" }, "description": "Supporting events/findings that generated this suggestion. Null unless requested with includeEvidence=true." }, "evidenceTotal": { "type": "number", "nullable": true, "description": "Uncapped total of supporting events behind this suggestion \u2014 `evidence` is a capped sample of these, so use this number when stating how often the pattern was seen. Null unless requested with includeEvidence=true." }, "diffChunks": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "label": { "type": "string" }, "before": { "type": "string" }, "after": { "type": "string" }, "kind": { "type": "string", "enum": [ "replace", "insert_after", "delete" ] }, "status": { "type": "string", "enum": [ "clean", "stale", "unverified" ] }, "diff": { "type": "string" } }, "required": [ "label", "before", "after", "kind", "status", "diff" ] }, "description": "Before/after diff chunks for the proposed change (each carries a ready-to-render fenced ```diff block). Null unless requested with includeDiff=true; empty when the suggestion has nothing diffable (add suggestions, doc rows stored before hunk capture, or full-doc rewrites)." }, "writeback": { "type": "object", "nullable": true, "properties": { "status": { "type": "string", "description": "Write outcome: succeeded, skipped, failed, pending." }, "skipReason": { "type": "string", "nullable": true, "description": "Why a skipped write was skipped." }, "target": { "type": "string", "nullable": true, "description": "Provider target key (e.g. google_drive). Null for rail-minted issues with no writable doc target (e.g. website pages)." }, "at": { "type": "string", "nullable": true, "format": "date-time", "description": "When the write attempt was last updated (ISO 8601)." } }, "required": [ "status", "skipReason", "target", "at" ], "description": "For accepted doc-update (Resource) suggestions: the upstream write's outcome \u2014 succeeded means the attributed comment landed in the doc. Null when no write has been attempted yet (accept is async \u2014 re-fetch to poll)." } }, "required": [ "oId", "status", "changeType", "suggestionType", "targetEntityType", "targetEntityOId", "name", "message", "summaryMessage", "attributes", "reasoning", "confidence", "createdAt", "docUpdate", "evidence", "evidenceTotal", "diffChunks", "writeback" ] }, "SuggestionEvidenceItem": { "type": "object", "properties": { "eventOId": { "type": "string", "description": "oId of the source event the finding came from." }, "findingOId": { "type": "string", "description": "oId of the extracted finding." }, "extractionType": { "type": "string", "enum": [ "EMAIL_INTERNAL_USE_CASE", "EMAIL_INTERNAL_PROOF_POINT", "EMAIL_INTERNAL_PAIN_POINT", "EMAIL_INTERNAL_BENEFITS_HIGHLIGHTED", "EMAIL_INTERNAL_VALUE_PROP", "EMAIL_INTERNAL_SOCIAL_PROOF", "EMAIL_INTERNAL_CALL_TO_ACTION", "EMAIL_INTERNAL_OBJECTION_HANDLING", "EMAIL_EXTERNAL_CALL_TO_ACTION", "EMAIL_EXTERNAL_OBJECTION", "EMAIL_EXTERNAL_QUESTION", "EMAIL_EXTERNAL_INTEREST_EXPRESSION", "EMAIL_EXTERNAL_FEATURE_REQUEST", "EMAIL_EXTERNAL_REQUIREMENT", "EMAIL_EXTERNAL_PRICING_FEEDBACK", "EMAIL_EXTERNAL_COMPARATIVE_STATEMENT", "EMAIL_EXTERNAL_KEY_TAKEAWAY", "EMAIL_EXTERNAL_COMPETITOR_MENTION", "EMAIL_EXTERNAL_NEXT_STEP", "EMAIL_EXTERNAL_URGENCY_INDICATOR", "EMAIL_EXTERNAL_DECISION_MAKING_SIGNAL", "EMAIL_EXTERNAL_UNIQUE_LANGUAGE_USED", "EMAIL_OVERALL_SENTIMENT", "EMAIL_TITLE_TO_PERSONA", "EMAIL_SEGMENT_DESCRIPTION", "SOCIAL_INTERNAL_USE_CASE", "SOCIAL_INTERNAL_PROOF_POINT", "SOCIAL_INTERNAL_PAIN_POINT", "SOCIAL_INTERNAL_VALUE_PROP", "SOCIAL_INTERNAL_SOCIAL_PROOF", "SOCIAL_INTERNAL_CALL_TO_ACTION", "SOCIAL_INTERNAL_BENEFITS_HIGHLIGHTED", "SOCIAL_INTERNAL_OBJECTION_HANDLING", "SOCIAL_TITLE_TO_PERSONA", "SOCIAL_SEGMENT_DESCRIPTION", "SOCIAL_PLAYBOOK_TOPICS", "SOCIAL_EXTERNAL_CALL_TO_ACTION", "SOCIAL_EXTERNAL_OBJECTION", "SOCIAL_EXTERNAL_QUESTION", "SOCIAL_EXTERNAL_INTEREST_EXPRESSION", "SOCIAL_EXTERNAL_FEATURE_REQUEST", "SOCIAL_EXTERNAL_REQUIREMENT", "SOCIAL_EXTERNAL_PRICING_FEEDBACK", "SOCIAL_EXTERNAL_COMPARATIVE_STATEMENT", "SOCIAL_EXTERNAL_KEY_TAKEAWAY", "SOCIAL_EXTERNAL_COMPETITOR_MENTION", "SOCIAL_EXTERNAL_NEXT_STEP", "SOCIAL_EXTERNAL_URGENCY_INDICATOR", "SOCIAL_EXTERNAL_DECISION_MAKING_SIGNAL", "SOCIAL_EXTERNAL_UNIQUE_LANGUAGE_USED", "SOCIAL_OVERALL_SENTIMENT", "CALL_EXTERNAL_BUSINESS_PROBLEMS", "CALL_EXTERNAL_IDEAL_SOLUTION_DESCRIPTION", "CALL_EXTERNAL_PRIMARY_GOALS", "CALL_EXTERNAL_WHY_ON_THIS_CALL", "CALL_EXTERNAL_STATUS_QUO_HOW_THEY_SOLVE_TODAY", "CALL_EXTERNAL_INDUSTRY_TRENDS", "CALL_EXTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_EXTERNAL_COMPETITORS_OF_THEIR_COMPANY", "CALL_EXTERNAL_CURRENT_TOOL_OR_SOLUTION_PROBLEMS", "CALL_EXTERNAL_OBJECTIONS", "CALL_EXTERNAL_PAIN_OR_PROBLEM_AGREEMENTS", "CALL_EXTERNAL_ROLE_OR_RESPONSIBILITIES_DESCRIPTION", "CALL_EXTERNAL_QUESTIONS_OR_CONFUSION_ABOUT_OFFERING", "CALL_EXTERNAL_CAPABILITIES_THAT_DREW_EXCITEMENT", "CALL_EXTERNAL_UNIQUE_LANGUAGE_USED", "CALL_EXTERNAL_FEATURE_REQUEST", "CALL_EXTERNAL_COMMITMENTS_MADE", "CALL_EXTERNAL_PRICING_OR_PACKAGING_FEEDBACK", "CALL_EXTERNAL_BLOCKERS_OR_DEPENDENCIES", "CALL_EXTERNAL_ABSENT_STAKEHOLDER_MENTIONS", "CALL_EXTERNAL_FRUSTRATION_OR_DISAPPOINTMENT", "CALL_EXTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_USE_CASES_BROUGHT_UP", "CALL_INTERNAL_PROOF_POINTS", "CALL_INTERNAL_REFERENCE_CUSTOMERS_OR_SOCIAL_PROOF", "CALL_INTERNAL_COMPETITORS", "CALL_INTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_INTERNAL_OBJECTION_HANDLING", "CALL_INTERNAL_VALUE_PROP_PRESENTATIONS", "CALL_INTERNAL_DIFFERENTIATED_VALUE", "CALL_INTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_COMPLEMENTARY_TOOLS_MENTIONED", "CALL_INTERNAL_COMMITMENTS_MADE", "CALL_COMPETITOR_MENTION_ORIGIN", "CALL_COMPETITOR_RELATIONSHIP_STATUS", "CALL_COMPETITOR_MENTAL_MODEL", "CALL_COMPETITOR_PROSPECT_VOICED_STRENGTH", "CALL_COMPETITOR_PROSPECT_VOICED_WEAKNESS", "CALL_COMPETITOR_OVERALL_STANCE", "CALL_COMPETITOR_HEAD_TO_HEAD_COMPARISON", "CALL_COMPETITOR_CONSIDERATION_SET_ALTERNATIVE", "CALL_COMPETITOR_COMMERCIAL_INTEL", "CALL_COMPETITOR_SWITCHING_TRIGGER_OR_BARRIER", "CALL_COMPETITOR_REP_CLAIM_REACTION", "CALL_COMPETITOR_DEAL_IMPACT", "CALL_CORE_FEATURE_MENTION_ORIGIN", "CALL_CORE_FEATURE_PROSPECT_LANGUAGE", "CALL_CORE_FEATURE_COMPREHENSION_CORRECTION", "CALL_CORE_FEATURE_PROSPECT_REACTION", "CALL_CORE_FEATURE_PROSPECT_QUESTION", "CALL_CORE_FEATURE_PROBLEM_ATTACHMENT", "CALL_CORE_FEATURE_VALUE_ARTICULATION", "CALL_CORE_FEATURE_CONCERN_OR_REQUIREMENT", "CALL_CORE_FEATURE_STATUS_QUO", "CALL_CORE_FEATURE_COMPARISON", "CALL_CORE_FEATURE_DECISION_WEIGHT", "CALL_CORE_FEATURE_USAGE_STAKEHOLDER", "RESOURCE_USE_CASES", "RESOURCE_PROOF_POINTS", "RESOURCE_REFERENCE_CUSTOMERS", "RESOURCE_COMPETITORS", "RESOURCE_OBJECTION_HANDLING", "RESOURCE_VALUE_PROPS", "RESOURCE_DIFFERENTIATED_VALUE", "RESOURCE_CORE_CAPABILITIES", "RESOURCE_SEGMENTS", "RESOURCE_INTEGRATIONS_PARTNERS", "RESOURCE_UNIQUE_LANGUAGE", "RESOURCE_PAIN_POINTS", "RESOURCE_TARGET_PERSONAS", "RESOURCE_ALTERNATIVES", "RESOURCE_BUYING_TRIGGERS", "CALL_OVERALL_SENTIMENT", "CALL_PURPOSE_CLASSIFICATION", "CALL_TITLE_TO_PERSONA", "CALL_SEGMENT_DESCRIPTION", "CRM_TITLE_TO_PERSONA", "CRM_SEGMENT_DESCRIPTION", "EVENT_SUMMARY", "BULK_IMPORT_THEMES", "BULK_LOSS_REASONS", "BULK_WIN_REASONS", "BULK_PAIN_POINTS", "BULK_USE_CASES", "BULK_COMPETITORS", "BULK_OBJECTIONS", "BULK_SEGMENTS", "BULK_PERSONAS", "ADS_INTERNAL_MESSAGING_THEME", "ADS_INTERNAL_TARGET_AUDIENCE", "ADS_INTERNAL_COMPETITIVE_POSITIONING", "ADS_INTERNAL_KEYWORD_TARGETING", "ADS_EXTERNAL_ENGAGEMENT_SIGNAL", "ADS_SEGMENT_DESCRIPTION", "ADS_MOTION_TYPE", "ADS_OFFERING_MATCH", "CALL_PROSPECT_RELATIONSHIP_TO_SELLER", "CALL_MOTION_TYPE", "CALL_OFFERING_MATCH", "EMAIL_PROSPECT_RELATIONSHIP_TO_SELLER", "EMAIL_MOTION_TYPE", "EMAIL_OFFERING_MATCH", "CRM_MOTION_TYPE", "CRM_OFFERING_MATCH", "RESOURCE_OFFERING_MATCH", "RESOURCE_TYPE_CLASSIFICATION", "CALL_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_TOPICS", "RESOURCE_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_SOURCE", "SOCIAL_PLAYBOOK_SOURCE", "CUSTOM" ], "description": "The extraction type of the finding." }, "actor": { "type": "string", "nullable": true, "description": "Who the finding is attributed to, when known." }, "text": { "type": "string", "description": "The verbatim source words behind the finding (what was said)." }, "snippetText": { "type": "string", "description": "The extractor's normalized claim \u2014 a short label ABOUT `text`, not a copy of it (e.g. 'Early adopter conversion rate' for a quote about giving the product to 20 clients)." }, "matchConfidence": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", null ], "description": "How confident the matcher was that this finding belongs to the suggestion's entity. Null when the extractor records no match analysis. Distinct from the suggestion's own `confidence`, which scores the proposal as a whole." }, "actorTitle": { "type": "string", "nullable": true, "description": "The speaking contact's job title, when the CRM knows it." }, "companyName": { "type": "string", "nullable": true, "description": "The company this finding is evidence FROM (the event's CRM-associated company, else an external participant's company)." }, "companyDomain": { "type": "string", "nullable": true, "description": "That company's domain." }, "providerName": { "type": "string", "nullable": true, "description": "The integration the source event came from, when known." }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the underlying event (call/email/meeting) actually occurred (ISO 8601)." } }, "required": [ "eventOId", "findingOId", "extractionType", "text", "snippetText", "providerName", "createdAt" ] }, "SuggestionCreateResult": { "allOf": [ { "$ref": "#/components/schemas/SuggestionSummary" }, { "type": "object", "properties": { "groupOId": { "type": "string", "description": "oId of the suggestion group the proposal was queued into." }, "message": { "type": "string", "description": "Human-readable confirmation of what was queued." } }, "required": [ "groupOId", "message" ] } ] }, "SuggestionSummary": { "type": "object", "properties": { "oId": { "type": "string", "description": "The suggestion's oId." }, "status": { "type": "string", "enum": [ "draft", "pending", "accepted", "rejected", "dismissed", "expired" ], "description": "Lifecycle status after the operation." }, "changeType": { "type": "string", "enum": [ "add", "refine" ], "description": "Friendly framing of the change: 'add' creates a brand new library entity; 'refine' changes an existing one.", "example": "add" }, "suggestionType": { "type": "string", "enum": [ "create_entity", "update_entity", "generate_entity", "refine_entity", "link_entities" ], "description": "The raw underlying suggestion type." }, "targetEntityType": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "Agent", "Hypothesis", "BrandVoice", "Resource" ], "description": "The library entity type being added or refined." }, "targetEntityOId": { "type": "string", "nullable": true, "description": "oId of the entity being refined (null for 'add')." } }, "required": [ "oId", "status", "changeType", "suggestionType", "targetEntityType", "targetEntityOId" ] }, "SuggestionAcceptResult": { "allOf": [ { "$ref": "#/components/schemas/SuggestionSummary" }, { "type": "object", "properties": { "resultingEntityOId": { "type": "string", "nullable": true, "description": "oId of the library entity created or updated by accepting." }, "resultingEntityName": { "type": "string", "nullable": true, "description": "Name of the resulting library entity, when resolvable." } }, "required": [ "resultingEntityOId", "resultingEntityName" ] } ] }, "SuggestionRejectResult": { "allOf": [ { "$ref": "#/components/schemas/SuggestionSummary" }, { "type": "object", "properties": { "reason": { "type": "string", "nullable": true, "description": "The reason that was persisted, or null if none was given." } }, "required": [ "reason" ] } ] }, "WorkspaceCompany": { "type": "object", "properties": { "oId": { "type": "string", "description": "Workspace Company OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "data": { "$ref": "#/components/schemas/WorkspaceCompanyData" }, "description": { "type": "string", "nullable": true, "description": "Workspace Company description" }, "name": { "type": "string", "description": "Workspace Company name" }, "url": { "type": "string", "description": "Workspace Company website URL" }, "internalName": { "type": "string", "nullable": true, "description": "Internal name for the workspace company" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" } }, "required": [ "oId" ], "description": "User who owns the workspace company" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace the company belongs to" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "url" ] }, "WorkspaceCompanyData": { "type": "object", "nullable": true, "properties": { "whatWeDo": { "type": "string", "nullable": true }, "whyWeExist": { "type": "array", "items": { "type": "string" } }, "howWePositionOurselves": { "type": "array", "items": { "type": "string" } }, "whoWeHelp": { "type": "array", "items": { "type": "string" } }, "whatMakesUsUnique": { "type": "array", "items": { "type": "string" } }, "businessModel": { "type": "array", "items": { "type": "string" } }, "marketDynamics": { "type": "array", "items": { "type": "string" } }, "whyCustomersBuy": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whyCustomersCare": { "type": "array", "nullable": true, "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "customMarketFields": { "$ref": "#/components/schemas/CustomDataFields" } }, "required": [ "whyWeExist", "howWePositionOurselves", "whoWeHelp", "whatMakesUsUnique", "businessModel", "marketDynamics" ] }, "ResolvedProfile": { "type": "object", "nullable": true, "properties": { "firstName": { "type": "string", "nullable": true, "example": "Jane" }, "lastName": { "type": "string", "nullable": true, "example": "Doe" }, "fullName": { "type": "string", "nullable": true, "example": "Jane Doe" }, "title": { "type": "string", "nullable": true, "example": "VP of Engineering" }, "headline": { "type": "string", "nullable": true, "description": "LinkedIn headline" }, "seniority": { "type": "string", "nullable": true, "description": "Normalized current seniority" }, "jobFunction": { "type": "string", "nullable": true, "description": "Normalized current job function" }, "linkedInUrl": { "type": "string", "nullable": true, "example": "https://www.linkedin.com/in/jane-doe" }, "linkedInSlug": { "type": "string", "nullable": true, "example": "jane-doe" }, "companyName": { "type": "string", "nullable": true, "example": "Acme" }, "companyDomain": { "type": "string", "nullable": true, "example": "acme.com" }, "companyLinkedInUrl": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true, "example": "San Francisco, CA" }, "city": { "type": "string", "nullable": true, "example": "San Francisco" }, "countryCode": { "type": "string", "nullable": true, "example": "US" }, "summary": { "type": "string", "nullable": true }, "photoUrl": { "type": "string", "nullable": true } } } }, "parameters": {} }, "paths": { "/api/v2/api-key/list": { "get": { "deprecated": false, "operationId": "listApiKeys", "summary": "List API keys", "description": "This endpoint returns a list of API keys. Rate limited to 1000 requests per minute.", "tags": [ "API Key" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 10, "example": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "default": 0, "example": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" }, { "schema": { "type": "string", "description": "Product OId" }, "required": false, "description": "Product OId", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "description": "Playbook OId" }, "required": false, "description": "Playbook OId", "name": "playbookOId", "in": "query" } ], "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyData" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/api-key/validate": { "get": { "deprecated": false, "operationId": "validateApiKey", "summary": "Validate API key", "description": "This endpoint validates the API key provided in the header. If the request succeeds, the API key is valid. Rate limited to 1000 requests per minute.", "tags": [ "API Key" ], "x-visibility": "public", "responses": { "200": { "description": "API key is valid", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "status": { "type": "string", "enum": [ "ok" ], "description": "Status of the API key validation", "example": "ok" }, "valid": { "type": "boolean", "description": "Whether the API key is valid", "example": true }, "workspaceOId": { "type": "string", "description": "The unique identifier for the workspace", "example": "wks_abc123" }, "workspaceName": { "type": "string", "description": "The name of the workspace", "example": "My Workspace" }, "workspaceDomain": { "type": "string", "nullable": true, "description": "The domain associated with the workspace", "example": "example.com" }, "organizationOId": { "type": "string", "description": "The unique identifier for the organization", "example": "org_xyz789" }, "organizationName": { "type": "string", "description": "The name of the organization", "example": "Acme Corp" }, "organizationDomain": { "type": "string", "description": "The domain associated with the organization", "example": "acme.com" }, "organizationSlug": { "type": "string", "description": "The URL-friendly slug for the organization", "example": "acme-corp" }, "mcpUrl": { "type": "string", "description": "The MCP server URL with encoded workspace context for connecting AI tools", "example": "https://mcp.octavehq.com/mcp?ctx=eyJvcmdhbml6YXRpb25fc2x1ZyI6ImFjbWUtY29ycCIsIndvcmtzcGFjZV9vX2lkIjoid2tzX2FiYzEyMyJ9" }, "credits": { "type": "object", "properties": { "totalUsed": { "type": "number", "description": "Total credits used (quota + subscription credits)", "example": 175 }, "totalRemaining": { "type": "number", "description": "Total credits remaining (quota + subscription credits)", "example": 425 }, "totalMax": { "type": "number", "description": "Total maximum credits available (quota + subscription credits)", "example": 575 }, "quotaUsed": { "type": "number", "description": "Number of credits used in the current period", "example": 150 }, "quotaAvailable": { "type": "number", "description": "Number of credits available in the current period", "example": 350 }, "quotaMax": { "type": "number", "description": "Maximum credits allowed in the current period", "example": 500 }, "period": { "type": "string", "description": "The tracking period for the credits (month, life, etc.)", "example": "month" }, "creditsUsed": { "type": "number", "description": "Credits used from subscription credit pool", "example": 25 }, "creditsAvailable": { "type": "number", "description": "Credits available from subscription credit pool", "example": 75 } }, "required": [ "totalUsed", "totalRemaining", "totalMax", "quotaUsed", "quotaAvailable", "quotaMax", "period", "creditsUsed", "creditsAvailable" ], "description": "Credit usage information for the API key" } }, "required": [ "_metadata", "status", "valid", "workspaceOId", "workspaceName", "workspaceDomain", "organizationOId", "organizationName", "organizationDomain", "organizationSlug", "mcpUrl", "credits" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "401": { "description": "Unauthorized - Invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "403": { "description": "Forbidden - API key validation failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/persona/get": { "get": { "deprecated": false, "operationId": "getPersona", "summary": "Get Persona", "description": "Get Persona by OId", "tags": [ "Persona" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Persona OId" }, "required": true, "description": "Persona OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Persona data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "Persona OId", "example": "p_1234" }, "name": { "type": "string", "nullable": true, "description": "Persona name", "example": "VP of Sales" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "nullable": true, "description": "Persona description" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether persona is unrecognized", "example": false }, "rejected": { "type": "boolean", "nullable": true, "description": "Whether persona is rejected", "example": false }, "active": { "type": "boolean", "default": true, "description": "Whether the persona is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/PersonData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the persona", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the persona", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the persona", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the persona belongs to", "example": "wa_1234" } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/persona/list": { "get": { "deprecated": false, "operationId": "listPersonas", "summary": "List persona", "description": "List personas by query", "tags": [ "Persona" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "text", "in": "query" }, { "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 10, "example": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "default": 0, "example": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Playbook OId" }, "required": false, "description": "Playbook OId", "name": "playbookOId", "in": "query" } ], "responses": { "200": { "description": "Persona data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Persona" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/persona/create": { "post": { "deprecated": false, "operationId": "createPersona", "summary": "Create Persona", "description": "Create a new persona", "tags": [ "Persona" ], "x-visibility": "public", "requestBody": { "description": "Persona creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The external name of the persona", "example": "VP of Sales" }, "internalName": { "type": "string", "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "description": "A description of the persona", "example": "Senior sales leaders responsible for revenue growth" }, "primaryResponsibilities": { "type": "array", "items": { "type": "string" }, "description": "The primary responsibilities of the persona", "example": [ "Drive revenue growth", "Manage sales team" ] }, "painPoints": { "type": "array", "items": { "type": "string" }, "description": "The pain points of the persona", "example": [ "Long sales cycles", "Difficulty tracking performance" ] }, "keyConcerns": { "type": "array", "items": { "type": "string" }, "description": "The key concerns of the persona", "example": [ "Meeting quotas", "Team productivity" ] }, "keyObjectives": { "type": "array", "items": { "type": "string" }, "description": "The key objectives of the persona", "example": [ "Increase revenue by 20%", "Reduce churn" ] }, "commonJobTitles": { "type": "array", "items": { "type": "string" }, "description": "The common job titles of the persona", "example": [ "VP of Sales", "Sales Director", "Chief Revenue Officer" ] }, "whyTheyMatterToUs": { "type": "array", "items": { "type": "string" }, "description": "The reasons why the persona matters to us", "example": [ "Decision makers", "Budget holders" ] }, "whyWeMatterToThem": { "type": "array", "items": { "type": "string" }, "description": "The reasons why we matter to this type of persona", "example": [ "Help achieve revenue goals", "Improve team efficiency" ] }, "buyingRole": { "type": "array", "items": { "type": "string" }, "description": "The function this persona typically plays in a purchase decision (e.g. economic buyer, champion, technical evaluator, end user, influencer, blocker), along with their level of sophistication on the problem space.", "example": [ "Economic buyer with budget authority over the GTM stack.", "Experienced operator who has evaluated similar tooling before." ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional persona information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this persona, keyed by property key.", "example": { "buying_role": "Champion", "seniority_level": "VP" } }, "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating personas. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "$ref": "#/components/schemas/LinkingStrategy" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Persona created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the persona", "example": "p_1234" }, "name": { "type": "string", "nullable": true, "description": "The name of the persona", "example": "VP of Sales" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "nullable": true, "description": "The description of the persona" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the persona was created", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was archived", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was updated", "example": "2021-01-01" }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the persona is unrecognized", "example": false }, "rejected": { "type": "boolean", "nullable": true, "description": "Whether the persona is rejected", "example": false }, "active": { "type": "boolean", "default": true, "description": "Whether the persona is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/PersonaData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the persona", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the persona", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the persona", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the persona belongs to", "example": "wa_1234" } } } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/persona/update": { "post": { "deprecated": false, "operationId": "updatePersona", "summary": "Update Persona", "description": "Update an existing persona", "tags": [ "Persona" ], "x-visibility": "public", "requestBody": { "description": "Persona update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the persona to update", "example": "p_1234" }, "name": { "type": "string", "description": "The external name of the persona", "example": "VP of Sales" }, "internalName": { "type": "string", "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "description": "A description of the persona", "example": "Senior sales leaders responsible for revenue growth" }, "primaryResponsibilities": { "type": "array", "items": { "type": "string" }, "description": "The primary responsibilities of the persona", "example": [ "Drive revenue growth", "Manage sales team" ] }, "painPoints": { "type": "array", "items": { "type": "string" }, "description": "The pain points of the persona", "example": [ "Long sales cycles", "Difficulty tracking performance" ] }, "keyConcerns": { "type": "array", "items": { "type": "string" }, "description": "The key concerns of the persona", "example": [ "Meeting quotas", "Team productivity" ] }, "keyObjectives": { "type": "array", "items": { "type": "string" }, "description": "The key objectives of the persona", "example": [ "Increase revenue by 20%", "Reduce churn" ] }, "commonJobTitles": { "type": "array", "items": { "type": "string" }, "description": "The common job titles of the persona", "example": [ "VP of Sales", "Sales Director", "Chief Revenue Officer" ] }, "whyTheyMatterToUs": { "type": "array", "items": { "type": "string" }, "description": "The reasons why the persona matters to us", "example": [ "Decision makers", "Budget holders" ] }, "whyWeMatterToThem": { "type": "array", "items": { "type": "string" }, "description": "The reasons why we matter to this type of persona", "example": [ "Help achieve revenue goals", "Improve team efficiency" ] }, "buyingRole": { "type": "array", "items": { "type": "string" }, "description": "The function this persona typically plays in a purchase decision (e.g. economic buyer, champion, technical evaluator, end user, influencer, blocker), along with their level of sophistication on the problem space (newcomer, experienced, expert).", "example": [ "Economic buyer with budget authority over the GTM stack.", "Experienced operator who has evaluated similar tooling before." ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional persona information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this persona, keyed by property key.", "example": { "buying_role": "Champion", "seniority_level": "VP" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Persona updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the persona", "example": "p_1234" }, "name": { "type": "string", "nullable": true, "description": "The name of the persona", "example": "VP of Sales" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "nullable": true, "description": "The description of the persona" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the persona was created", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was archived", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was updated", "example": "2021-01-01" }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the persona is unrecognized", "example": false }, "rejected": { "type": "boolean", "nullable": true, "description": "Whether the persona is rejected", "example": false }, "active": { "type": "boolean", "default": true, "description": "Whether the persona is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/PersonaData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the persona", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the persona", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the persona", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the persona belongs to", "example": "wa_1234" } } } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Persona not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/persona/generate": { "post": { "deprecated": false, "operationId": "generatePersonas", "summary": "Generate Personas", "description": "Generate personas from source materials using AI. Each input array generates one persona. Supports text, URLs, and generative names as sources.", "tags": [ "Persona" ], "x-visibility": "public", "requestBody": { "description": "Persona generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating personas. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking generated personas to offerings (products/services)" } ] }, "personas": { "$ref": "#/components/schemas/PersonaGenerationInputs" }, "playbookOId": { "type": "string", "description": "Optional playbook ID to link the generated personas to", "example": "pb_456" }, "brandVoiceOId": { "type": "string", "description": "Optional brand voice ID to apply to generated personas", "example": "bv_789" }, "async": { "type": "boolean", "description": "If true, the persona generation will be processed asynchronously", "example": false }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. When provided with async: true, the API will POST the result to this URL once processing completes.", "example": "https://example.com/webhook/persona" } }, "required": [ "personas" ] } } } }, "responses": { "200": { "description": "Personas generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the persona", "example": "p_1234" }, "name": { "type": "string", "nullable": true, "description": "The name of the persona", "example": "VP of Sales" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "nullable": true, "description": "The description of the persona" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the persona was created", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was archived", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the persona was updated", "example": "2021-01-01" }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the persona is unrecognized", "example": false }, "rejected": { "type": "boolean", "nullable": true, "description": "Whether the persona is rejected", "example": false }, "active": { "type": "boolean", "default": true, "description": "Whether the persona is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/PersonaData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the persona", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the persona", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the persona", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the persona belongs to", "example": "wa_1234" } } } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } } }, "required": [ "_metadata" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/persona/delete": { "delete": { "deprecated": false, "operationId": "deletePersona", "summary": "Delete Persona", "description": "Soft delete a Persona by OId. The persona will be marked as deleted but not permanently removed.", "tags": [ "Persona" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Persona OId" }, "required": true, "description": "Persona OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted persona data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "Persona OId", "example": "p_1234" }, "name": { "type": "string", "nullable": true, "description": "Persona name", "example": "VP of Sales" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "nullable": true, "description": "Persona description" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether persona is unrecognized", "example": false }, "rejected": { "type": "boolean", "nullable": true, "description": "Whether persona is rejected", "example": false }, "active": { "type": "boolean", "default": true, "description": "Whether the persona is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/PersonData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the persona", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the persona", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the persona", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the persona belongs to", "example": "wa_1234" } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Persona not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/list": { "get": { "deprecated": false, "operationId": "listAgents", "summary": "List Agents", "description": "List all agents", "tags": [ "Agents" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT", null ], "description": "Type of the agent to list" }, "required": false, "description": "Type of the agent to list", "name": "type", "in": "query" }, { "schema": { "type": "string", "nullable": true, "default": "", "description": "Query for which agents to list" }, "required": false, "description": "Query for which agents to list", "name": "query", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset of the agent to list" }, "required": false, "description": "Offset of the agent to list", "name": "offset", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit of the agent to list" }, "required": false, "description": "Limit of the agent to list", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "createdAt", "updatedAt" ], "default": "createdAt", "description": "Field to order the agents by" }, "required": false, "description": "Field to order the agents by", "name": "orderField", "in": "query" }, { "schema": { "type": "string", "enum": [ "ASC", "DESC" ], "default": "DESC", "description": "Direction to order the agents by" }, "required": false, "description": "Direction to order the agents by", "name": "orderDirection", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": false, "description": "Whether to include experiments in the results. Only applies to EMAIL and CONTENT agent types. NOTE: when set to true, the response will be a list of agents and experiments so the total will be the sum of the agents and experiments and you may receive more items than the limit." }, "required": false, "description": "Whether to include experiments in the results. Only applies to EMAIL and CONTENT agent types. NOTE: when set to true, the response will be a list of agents and experiments so the total will be the sum of the agents and experiments and you may receive more items than the limit.", "name": "includeExperiments", "in": "query" } ], "responses": { "200": { "description": "List agents successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "oId": { "type": "string", "description": "The OId of the item" }, "name": { "type": "string", "description": "The name of the item" }, "description": { "type": "string", "nullable": true, "description": "The description of the item" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The creation date of the item" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The last updated date of the item" }, "type": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ], "description": "The type of the agent" }, "costToRun": { "type": "number", "description": "The cost to run the item" }, "steps": { "type": "number", "description": "The number of steps in the agent. Only available for email agents." }, "itemType": { "type": "string", "enum": [ "agent" ], "description": "Indicates this is an individual agent (only present when includeExperiments=true)" }, "contentOutputFormat": { "type": "string", "enum": [ "JSON", "TEXT", "HTML", "MARKDOWN" ], "description": "The output format of the Agent (only available for CONTENT agents)" } }, "required": [ "oId", "name", "createdAt", "updatedAt", "type" ] }, { "type": "object", "properties": { "oId": { "type": "string", "description": "The OId of the item" }, "name": { "type": "string", "description": "The name of the item" }, "description": { "type": "string", "nullable": true, "description": "The description of the item" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The creation date of the item" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The last updated date of the item" }, "type": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ], "description": "The type of the agent" }, "costToRun": { "type": "number", "description": "The cost to run the item" }, "steps": { "type": "number", "description": "The number of steps in the agent. Only available for email agents." }, "itemType": { "type": "string", "enum": [ "experiment" ], "description": "Indicates this is an experiment containing multiple agents" }, "runStrategy": { "type": "string", "nullable": true, "enum": [ "RANDOM", "ROUND_ROBIN", "WEIGHTED", null ], "description": "The run strategy for the experiment" } }, "required": [ "oId", "name", "createdAt", "updatedAt", "type", "itemType" ] } ] } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/types": { "get": { "deprecated": false, "operationId": "listAgentTypes", "summary": "List Agent Types", "description": "List all available agent types with their metadata", "tags": [ "Agents" ], "x-visibility": "public", "responses": { "200": { "description": "List agent types successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "total": { "type": "number", "example": 9, "description": "Total number of agent types" }, "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ], "description": "The agent type identifier" }, "name": { "type": "string", "description": "The human-readable name of the agent type" }, "description": { "type": "string", "description": "A description of what this agent type does" }, "category": { "type": "string", "description": "The category this agent type belongs to" } }, "required": [ "type", "name", "description", "category" ] } } }, "required": [ "_metadata", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/create": { "post": { "deprecated": false, "operationId": "createAgent", "summary": "Create Agent", "description": "Create a new agent", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Agent creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the agent", "example": "Cold Outbound Sequence" }, "description": { "type": "string", "minLength": 1, "description": "The description of the agent", "example": "A cold outbound email sequence agent" }, "type": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ], "description": "The type of agent to create" }, "model": { "type": "string", "enum": [ "NOTE", "PULSE", "ECHO", "HARMONY", "CHORUS", "SYMPHONY" ], "description": "The model to use for the agent" }, "productOId": { "type": "string", "description": "The OId of the product/offering to associate with the agent" }, "serviceOId": { "type": "string", "description": "Alias for productOId \u2014 use either field, not both. Maps to the same internal product/offering." }, "playbookOId": { "type": "string", "description": "The OId of the playbook to associate with the agent" }, "personaOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the personas to associate with the agent" }, "useCaseOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the use cases to associate with the agent" }, "segmentOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the segments to associate with the agent" }, "competitorOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the competitors to associate with the agent" }, "referenceOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the reference customers to associate with the agent" }, "proofPointOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the proof points to associate with the agent" }, "motionPlaybookOIds": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Motion playbook OIds to pin onto the agent. All provided OIds MUST belong to the same parent motion \u2014 the request is rejected if they span multiple motions. The parent motion is auto-derived and pinned alongside. Only applied for EMAIL (sequence), CONTENT, and CALL_PREP agent types \u2014 silently ignored for other types." }, "enableBrandVoice": { "type": "boolean", "description": "Whether to enable brand voice for the agent" }, "enableWebSearch": { "type": "boolean", "description": "Whether to enable web search. Only enable when explicitly requested" }, "webSearchInstructions": { "type": "string", "description": "Custom instructions for the web search tool" }, "enableCrmActivity": { "type": "boolean", "description": "Whether to enable CRM activity for the agent" }, "crmActivityInstructions": { "type": "string", "description": "Custom instructions for the CRM activity tool" }, "enableHighEffortMode": { "type": "boolean", "description": "Whether to enable high-effort mode for the agent" }, "sequenceSettings": { "type": "object", "properties": { "sequenceType": { "type": "string", "enum": [ "COLD_OUTBOUND", "WARM_OUTBOUND", "INBOUND", "CUSTOM", "CVI_WHY_CHANGE", "BARE_METAL" ], "description": "Sequence type (e.g. COLD_OUTBOUND, WARM_OUTBOUND). Changing this does not reset step-level configs." }, "numEmails": { "type": "number", "nullable": true, "description": "Number of emails in the sequence (default 4)" }, "sequenceTypeCustomInstructions": { "type": "string", "nullable": true, "description": "Custom instructions specific to the sequence type (e.g. context about the cold outbound campaign)" }, "sequenceCustomInstructions": { "type": "string", "nullable": true, "description": "General custom instructions applied across the entire sequence" }, "writingStyleOId": { "type": "string", "nullable": true, "description": "OId of a saved writing style to apply to the sequence" }, "generateUniqueSubjectLines": { "type": "boolean", "nullable": true, "description": "If true, generate a unique subject line per email instead of reusing one" }, "tone": { "type": "string", "enum": [ "Casual", "Neutral", "Formal" ], "description": "Writing tone applied to all emails (e.g. Casual, Professional, Formal)" }, "readingLevel": { "type": "string", "enum": [ "8th Grade", "High School", "College", "Professional" ], "description": "Reading level for generated text (e.g. High School, College, PhD)" }, "applyCtaToAllEmails": { "type": "boolean", "description": "If true, apply the same CTA config to every email in the sequence" }, "applySubjectToAllEmails": { "type": "boolean", "description": "If true, apply the same subject config to every email in the sequence" } }, "description": "EMAIL agents only: sequence-level settings (type, numEmails, tone, reading level, instructions, writingStyleOId, etc.)" }, "stepPatches": { "type": "object", "additionalProperties": { "type": "object", "properties": { "methodology": { "type": "string", "enum": [ "Octave", "Octave + Custom", "Custom" ], "description": "Sales methodology for this step. Set to Custom or Octave + Custom when providing customInstructions." }, "focus": { "type": "string", "nullable": true, "enum": [ "Pain", "Neutral", "Benefits", null ], "description": "Email focus area for this step (e.g. PAIN_POINT, PRODUCT)" }, "customInstructions": { "type": "string", "description": "Custom instructions for this step. Only applied when methodology is Custom or Octave + Custom." }, "length": { "type": "object", "properties": { "wordCountPreset": { "type": "string", "enum": [ "EXTRA_SHORT", "SHORT", "MEDIUM", "LONG", "EXTRA_LONG", "CUSTOM" ] }, "wordCount": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "min", "max" ] }, "numSentences": { "type": "number" }, "numParagraphs": { "type": "number" } }, "description": "Length controls: wordCountPreset (SHORT, MEDIUM, LONG, EXTRA_SHORT) or custom wordCount min/max, numSentences, numParagraphs" }, "subject": { "type": "object", "properties": { "includePersonName": { "type": "boolean" }, "includeCompanyName": { "type": "boolean" }, "allLowercase": { "type": "boolean" }, "length": { "type": "object", "properties": { "minWords": { "type": "number" }, "maxWords": { "type": "number" } } }, "customInstructions": { "type": "string" }, "examples": { "type": "array", "items": { "type": "string" } } }, "description": "Subject line configuration for this step" }, "cta": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "INITIATE_CONVERSATION", "SCHEDULE_MEETING", "REQUEST_INTRODUCTION", "ASK_FOR_FEEDBACK", "FIND_TIME_TO_CONNECT", "POLITELY_DISENGAGE", "SMART_CTA" ] }, { "type": "string", "enum": [ "CUSTOM" ] } ], "description": "CTA preset or CUSTOM for free-form CTA instructions" }, "customInstructions": { "type": "string", "description": "Custom CTA instructions (only used when type is CUSTOM)" }, "smartCtaConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "NONE", "AUTO", "SPECIFIC" ], "description": "Smart CTA mode controlling how CTAs are generated" }, "ctaOIds": { "type": "array", "items": { "type": "string" }, "description": "OIds of smart CTA entities to use" } }, "description": "Smart CTA configuration for AI-generated CTAs" } }, "description": "Call-to-action configuration for this step" }, "trainingExamples": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "paste", "updatePaste", "remove" ], "description": "paste: create a new training example; updatePaste: update an existing one in place; remove: delete a training example from the step" }, "bodyText": { "type": "string", "minLength": 1, "description": "The example email body text. Required for paste and updatePaste modes; ignored for remove." }, "flexibility": { "type": "string", "nullable": true, "enum": [ "STRICT", "LOOSE", null ], "description": "How closely the generated email should follow this example (e.g. STRICT, FLEXIBLE)" }, "targetTrainingIndex": { "type": "integer", "minimum": 1, "description": "For updatePaste/remove: 1-based index into this step's training examples (first example is 1). Omitted means 1. Ignored for paste." } }, "required": [ "mode" ], "description": "Training example management: paste new examples, update existing ones, or remove them" }, "skipReferenceCustomer": { "type": "boolean", "description": "If true, skip reference customer mentions in this step" }, "skipProofPoint": { "type": "boolean", "description": "If true, skip proof point mentions in this step" }, "stepCustomPrompt": { "type": "string", "description": "Custom prompt appended to this step's generation instructions" } } }, "description": "EMAIL agents only: map of 1-based step index to partial email builder config (methodology, focus, length, cta, subject, trainingExamples: paste or updatePaste \u2014 no raw smart-example oIds), same numbering as sequence run runtimeContext keys. Deep-merged into writingStyle.emails[i]. trainingExamples.targetTrainingIndex is 1-based (default 1)." }, "callPrepMethodology": { "type": "string", "enum": [ "BANT", "SPIN", "CHAMP", "MEDDIC", "SANDLER", "CHALLENGER", "AIDA", "NEAT", "SPICED", "WHY_CHANGE" ], "description": "Call prep methodology (CALL_PREP agents only). Controls discovery questions and call script framing." }, "instructions": { "type": "string", "description": "Instructions for content generation (CONTENT agents only)" }, "examples": { "type": "array", "items": { "type": "string" }, "description": "Example outputs for content generation (CONTENT agents only)" }, "outputFormat": { "type": "string", "enum": [ "JSON", "TEXT", "HTML", "MARKDOWN" ], "description": "The output format for content generation (CONTENT agents only)" }, "jsonSchemaInstructions": { "type": "string", "description": "JSON schema instructions for content generation (CONTENT agents only, used with JSON output format)" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Full agent configuration data passthrough. When provided, this will be merged with the simplified fields above, with simplified fields taking precedence." } }, "required": [ "name", "description", "type" ] } } } }, "responses": { "200": { "description": "Agent created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "description": "The OId of the agent" }, "name": { "type": "string", "description": "The name of the agent" }, "description": { "type": "string", "description": "The description of the agent" }, "type": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ], "description": "The type of the agent" }, "data": { "nullable": true, "description": "The full agent configuration data" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The creation date of the agent" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The last updated date of the agent" }, "costToRun": { "type": "number", "description": "The cost to run the agent" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Warnings about type-mismatched fields that were provided but ignored" } }, "required": [ "oId", "name", "description", "type", "createdAt", "updatedAt", "costToRun" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/update": { "post": { "deprecated": false, "operationId": "updateAgent", "summary": "Update Agent", "description": "Update an existing agent", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Agent update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The OId of the agent to update", "example": "agent_123" }, "name": { "type": "string", "description": "The name of the agent" }, "description": { "type": "string", "description": "The description of the agent" }, "model": { "type": "string", "enum": [ "NOTE", "PULSE", "ECHO", "HARMONY", "CHORUS", "SYMPHONY" ], "description": "The model to use for the agent" }, "productOId": { "type": "string", "description": "The OId of the product/offering to associate with the agent" }, "serviceOId": { "type": "string", "description": "Alias for productOId \u2014 use either field, not both. Maps to the same internal product/offering." }, "playbookOId": { "type": "string", "description": "The OId of the playbook to associate with the agent" }, "personaOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the personas to associate with the agent" }, "useCaseOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the use cases to associate with the agent" }, "segmentOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the segments to associate with the agent" }, "competitorOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the competitors to associate with the agent" }, "referenceOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the reference customers to associate with the agent" }, "proofPointOIds": { "type": "array", "items": { "type": "string" }, "description": "The OIds of the proof points to associate with the agent" }, "motionPlaybookOIds": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Motion playbook OIds to pin onto the agent. All provided OIds MUST belong to the same parent motion \u2014 the request is rejected if they span multiple motions. The parent motion is auto-derived and pinned alongside. Only applied for EMAIL (sequence), CONTENT, and CALL_PREP agent types \u2014 silently ignored for other types. Pass null (or []) to clear an existing pinning; omit to leave it alone." }, "enableBrandVoice": { "type": "boolean", "description": "Whether to enable brand voice for the agent" }, "enableWebSearch": { "type": "boolean", "description": "Whether to enable web search. Only enable when explicitly requested" }, "webSearchInstructions": { "type": "string", "description": "Custom instructions for the web search tool" }, "enableCrmActivity": { "type": "boolean", "description": "Whether to enable CRM activity for the agent" }, "crmActivityInstructions": { "type": "string", "description": "Custom instructions for the CRM activity tool" }, "enableHighEffortMode": { "type": "boolean", "description": "Whether to enable high-effort mode for the agent" }, "sequenceSettings": { "type": "object", "properties": { "sequenceType": { "type": "string", "enum": [ "COLD_OUTBOUND", "WARM_OUTBOUND", "INBOUND", "CUSTOM", "CVI_WHY_CHANGE", "BARE_METAL" ], "description": "Sequence type (e.g. COLD_OUTBOUND, WARM_OUTBOUND). Changing this does not reset step-level configs." }, "numEmails": { "type": "number", "nullable": true, "description": "Number of emails in the sequence (default 4)" }, "sequenceTypeCustomInstructions": { "type": "string", "nullable": true, "description": "Custom instructions specific to the sequence type (e.g. context about the cold outbound campaign)" }, "sequenceCustomInstructions": { "type": "string", "nullable": true, "description": "General custom instructions applied across the entire sequence" }, "writingStyleOId": { "type": "string", "nullable": true, "description": "OId of a saved writing style to apply to the sequence" }, "generateUniqueSubjectLines": { "type": "boolean", "nullable": true, "description": "If true, generate a unique subject line per email instead of reusing one" }, "tone": { "type": "string", "enum": [ "Casual", "Neutral", "Formal" ], "description": "Writing tone applied to all emails (e.g. Casual, Professional, Formal)" }, "readingLevel": { "type": "string", "enum": [ "8th Grade", "High School", "College", "Professional" ], "description": "Reading level for generated text (e.g. High School, College, PhD)" }, "applyCtaToAllEmails": { "type": "boolean", "description": "If true, apply the same CTA config to every email in the sequence" }, "applySubjectToAllEmails": { "type": "boolean", "description": "If true, apply the same subject config to every email in the sequence" } }, "description": "EMAIL agents only: sequence-level settings (type, numEmails, tone, reading level, instructions, writingStyleOId, etc.)" }, "stepPatches": { "type": "object", "additionalProperties": { "type": "object", "properties": { "methodology": { "type": "string", "enum": [ "Octave", "Octave + Custom", "Custom" ], "description": "Sales methodology for this step. Set to Custom or Octave + Custom when providing customInstructions." }, "focus": { "type": "string", "nullable": true, "enum": [ "Pain", "Neutral", "Benefits", null ], "description": "Email focus area for this step (e.g. PAIN_POINT, PRODUCT)" }, "customInstructions": { "type": "string", "description": "Custom instructions for this step. Only applied when methodology is Custom or Octave + Custom." }, "length": { "type": "object", "properties": { "wordCountPreset": { "type": "string", "enum": [ "EXTRA_SHORT", "SHORT", "MEDIUM", "LONG", "EXTRA_LONG", "CUSTOM" ] }, "wordCount": { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "min", "max" ] }, "numSentences": { "type": "number" }, "numParagraphs": { "type": "number" } }, "description": "Length controls: wordCountPreset (SHORT, MEDIUM, LONG, EXTRA_SHORT) or custom wordCount min/max, numSentences, numParagraphs" }, "subject": { "type": "object", "properties": { "includePersonName": { "type": "boolean" }, "includeCompanyName": { "type": "boolean" }, "allLowercase": { "type": "boolean" }, "length": { "type": "object", "properties": { "minWords": { "type": "number" }, "maxWords": { "type": "number" } } }, "customInstructions": { "type": "string" }, "examples": { "type": "array", "items": { "type": "string" } } }, "description": "Subject line configuration for this step" }, "cta": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "INITIATE_CONVERSATION", "SCHEDULE_MEETING", "REQUEST_INTRODUCTION", "ASK_FOR_FEEDBACK", "FIND_TIME_TO_CONNECT", "POLITELY_DISENGAGE", "SMART_CTA" ] }, { "type": "string", "enum": [ "CUSTOM" ] } ], "description": "CTA preset or CUSTOM for free-form CTA instructions" }, "customInstructions": { "type": "string", "description": "Custom CTA instructions (only used when type is CUSTOM)" }, "smartCtaConfig": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "NONE", "AUTO", "SPECIFIC" ], "description": "Smart CTA mode controlling how CTAs are generated" }, "ctaOIds": { "type": "array", "items": { "type": "string" }, "description": "OIds of smart CTA entities to use" } }, "description": "Smart CTA configuration for AI-generated CTAs" } }, "description": "Call-to-action configuration for this step" }, "trainingExamples": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "paste", "updatePaste", "remove" ], "description": "paste: create a new training example; updatePaste: update an existing one in place; remove: delete a training example from the step" }, "bodyText": { "type": "string", "minLength": 1, "description": "The example email body text. Required for paste and updatePaste modes; ignored for remove." }, "flexibility": { "type": "string", "nullable": true, "enum": [ "STRICT", "LOOSE", null ], "description": "How closely the generated email should follow this example (e.g. STRICT, FLEXIBLE)" }, "targetTrainingIndex": { "type": "integer", "minimum": 1, "description": "For updatePaste/remove: 1-based index into this step's training examples (first example is 1). Omitted means 1. Ignored for paste." } }, "required": [ "mode" ], "description": "Training example management: paste new examples, update existing ones, or remove them" }, "skipReferenceCustomer": { "type": "boolean", "description": "If true, skip reference customer mentions in this step" }, "skipProofPoint": { "type": "boolean", "description": "If true, skip proof point mentions in this step" }, "stepCustomPrompt": { "type": "string", "description": "Custom prompt appended to this step's generation instructions" } } }, "description": "EMAIL agents only: map of 1-based step index to partial email builder config (same numbering as sequence run runtimeContext keys). Deep-merged into writingStyle.emails[i] after update. trainingExamples.targetTrainingIndex is 1-based (default 1)." }, "callPrepMethodology": { "type": "string", "enum": [ "BANT", "SPIN", "CHAMP", "MEDDIC", "SANDLER", "CHALLENGER", "AIDA", "NEAT", "SPICED", "WHY_CHANGE" ], "description": "Call prep methodology (CALL_PREP agents only). Controls discovery questions and call script framing." }, "instructions": { "type": "string", "description": "Instructions for content generation (CONTENT agents only)" }, "examples": { "type": "array", "items": { "type": "string" }, "description": "Example outputs for content generation (CONTENT agents only)" }, "outputFormat": { "type": "string", "enum": [ "JSON", "TEXT", "HTML", "MARKDOWN" ], "description": "The output format for content generation (CONTENT agents only)" }, "jsonSchemaInstructions": { "type": "string", "description": "JSON schema instructions for content generation (CONTENT agents only, used with JSON output format)" }, "data": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Full agent configuration data passthrough. When provided, this will be merged with the simplified fields above, with simplified fields taking precedence." } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Agent updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "description": "The OId of the agent" }, "name": { "type": "string", "description": "The name of the agent" }, "description": { "type": "string", "description": "The description of the agent" }, "type": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ], "description": "The type of the agent" }, "data": { "nullable": true, "description": "The full agent configuration data" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The creation date of the agent" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The last updated date of the agent" }, "costToRun": { "type": "number", "description": "The cost to run the agent" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Warnings about type-mismatched fields that were provided but ignored" } }, "required": [ "oId", "name", "description", "type", "createdAt", "updatedAt", "costToRun" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/get": { "get": { "deprecated": false, "operationId": "getAgent", "summary": "Get Agent", "description": "Get Agent by OId", "tags": [ "Agents" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Agent OId" }, "required": true, "description": "Agent OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Agent data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "description": "The OId of the agent" }, "name": { "type": "string", "description": "The name of the agent" }, "description": { "type": "string", "description": "The description of the agent" }, "type": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ], "description": "The type of the agent" }, "data": { "nullable": true, "description": "The full agent configuration data" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The creation date of the agent" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The last updated date of the agent" }, "costToRun": { "type": "number", "description": "The cost to run the agent" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Warnings about type-mismatched fields that were provided but ignored" } }, "required": [ "oId", "name", "description", "type", "createdAt", "updatedAt", "costToRun" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/delete": { "delete": { "deprecated": false, "operationId": "deleteAgent", "summary": "Delete Agent", "description": "Soft delete an Agent by OId. The agent will be marked as deleted but not permanently removed.", "tags": [ "Agents" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Agent OId" }, "required": true, "description": "Agent OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted agent data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "description": "The OId of the agent" }, "name": { "type": "string", "description": "The name of the agent" }, "description": { "type": "string", "description": "The description of the agent" }, "type": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ], "description": "The type of the agent" }, "data": { "nullable": true, "description": "The full agent configuration data" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The creation date of the agent" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The last updated date of the agent" }, "costToRun": { "type": "number", "description": "The cost to run the agent" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Warnings about type-mismatched fields that were provided but ignored" } }, "required": [ "oId", "name", "description", "type", "createdAt", "updatedAt", "costToRun" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/languages": { "get": { "deprecated": false, "operationId": "listLanguages", "summary": "List Languages", "description": "List supported languages", "tags": [ "Agents" ], "x-visibility": "public", "responses": { "200": { "description": "List languages successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "flag": { "type": "string" } }, "required": [ "name", "code", "flag" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/enrich-company/run": { "post": { "deprecated": false, "operationId": "runEnrichCompanyAgent", "summary": "Enrich Company Agent", "description": "Enrich a company", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Enrichment input", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyDomain": { "type": "string", "nullable": true, "description": "Company domain to enrich", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name to enrich", "example": "Example" }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context", "example": { "user": { "oId": "user_123" } } }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } }, "required": [ "agentOId" ] } } } }, "responses": { "200": { "description": "Enrichment successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/EnrichCompanyAgentData" } }, "required": [ "_metadata", "found" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/enrich-person/run": { "post": { "deprecated": false, "operationId": "runEnrichPersonAgent", "summary": "Enrich Person Agent", "description": "Enrich a Person", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Enrichment input", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to enrich", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to enrich", "example": "John" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to enrich", "example": "Software Engineer" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain of the person to enrich" }, "companyName": { "type": "string", "nullable": true, "description": "Company name of the person to enrich", "example": "Example" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to enrich", "example": "https://www.linkedin.com/in/john-doe/" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context", "example": { "user": { "oId": "user_123" } } }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } }, "required": [ "agentOId" ] } } } }, "responses": { "200": { "description": "Enrichment successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/EnrichPersonAgentData" } }, "required": [ "_metadata", "found" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/generate-content/run": { "post": { "deprecated": false, "operationId": "runContentAgent", "summary": "Content Agent", "description": "Generate content for a person", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Generate content input", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to generate content for", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to generate content for" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to generate content for" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain to generate content for", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name to generate content for" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to generate content for" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context" }, "url": { "type": "string", "nullable": true, "description": "URL to generate content for" }, "customContext": { "type": "object", "nullable": true, "properties": { "playbook": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "product": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "service": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "persona": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "segment": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] } }, "description": "Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning).", "example": { "persona": { "oId": "pe_xxxxxxxxxxxxxxxxxxxxx" }, "segment": { "oId": "sg_xxxxxxxxxxxxxxxxxxxxx" } } }, "outputFormat": { "type": "string", "nullable": true, "enum": [ "JSON", "TEXT", "HTML", "MARKDOWN", null ] }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "experimentOId": { "type": "string", "description": "ExperimentOId is required when running an experiment", "example": "experiment_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } } } } } }, "responses": { "200": { "description": "Generate content successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/GeneratedContentData" } }, "required": [ "_metadata", "found" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/sequence/run": { "post": { "deprecated": false, "operationId": "runSequenceAgent", "summary": "Sequence Agent", "description": "Generate Emails for a person", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Generate emails input", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to generate emails for", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to generate emails for" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to generate emails for" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain of the person to generate emails for", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name of the person to generate emails for" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to generate emails for" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "lang": { "type": "string", "nullable": true, "description": "Language of the person to generate emails for" }, "requestId": { "type": "string", "nullable": true }, "outputFormat": { "type": "string", "nullable": true, "enum": [ "text", "html", "markdown", null ], "default": "text", "description": "Output format of the emails to generate" }, "runtimeContext": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional context (facts, research, account data) injected at runtime to personalize the generated sequence. Keys control which email steps receive the context: \"all\" applies to every email, \"1\"-\"4\" apply to a specific step (1-based index). Step-specific context is merged with the \"all\" context.", "example": { "1": "Reference her AWS SCA leadership role in the opening.", "all": "Account research: NICE Ltd expanded their AI partner program from 25 to 200 partners. Sarah leads strategic alliances." } }, "runtimeInstructions": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Behavioral directives that control how the agent writes the sequence \u2014 tone, structure, emphasis, constraints. Keys work the same way as runtimeContext: \"all\" applies to every email, \"1\"-\"4\" apply to a specific step (1-based index). Use runtimeInstructions for writing style directives. Use runtimeContext for factual data.", "example": { "1": "Lead with a specific personal detail \u2014 do not open with a generic intro.", "all": "Keep emails under 150 words. Use a consultative tone, not salesy." } }, "playbookSelectionContext": { "type": "string", "nullable": true, "description": "Playbook selection context of the person to generate emails for" }, "customContext": { "type": "object", "nullable": true, "properties": { "playbook": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "product": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "service": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "persona": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "segment": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] } }, "description": "Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning).", "example": { "persona": { "oId": "pe_xxxxxxxxxxxxxxxxxxxxx" }, "segment": { "oId": "sg_xxxxxxxxxxxxxxxxxxxxx" } } }, "fullSequenceMode": { "type": "boolean" }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "experimentOId": { "type": "string", "description": "ExperimentOId is required when running an experiment", "example": "experiment_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } } } } } }, "responses": { "200": { "description": "Generate emails successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/EmailAgentData" } }, "required": [ "_metadata", "found" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/playbook/get": { "get": { "deprecated": false, "operationId": "getPlaybook", "summary": "Get Playbook", "description": "Get Playbook by OId", "tags": [ "Playbook" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Playbook OId" }, "required": true, "description": "Playbook OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Playbook data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/PlaybookData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "active": { "type": "boolean", "default": true }, "type": { "type": "string", "nullable": true, "enum": [ "LEGACY", "SECTOR", "SOLUTION", "MILESTONE", "PRACTITIONER", "COMPETITIVE", "ACCOUNT", "CUSTOM", null ] }, "framework": { "type": "string", "nullable": true, "enum": [ "CVI_WHY_CHANGE", null ] }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ], "default": "active" }, "referenceMode": { "type": "string", "enum": [ "specific", "none" ], "default": "specific" }, "proofPointMode": { "type": "string", "enum": [ "specific", "none" ], "default": "none" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "product": { "$ref": "#/components/schemas/PlaybookProduct" }, "service": { "$ref": "#/components/schemas/PlaybookService" }, "buyerPersonas": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookPersona" } }, "useCases": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookUseCase" } }, "references": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookReference" } }, "segment": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } }, "competitor": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } }, "proofPoints": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } } } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/playbook/list": { "get": { "deprecated": false, "operationId": "listPlaybooks", "summary": "List Playbooks", "description": "List Playbooks", "tags": [ "Playbook" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Text to search for" }, "required": false, "description": "Text to search for", "name": "text", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit the number of results" }, "required": false, "description": "Limit the number of results", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset the results" }, "required": false, "description": "Offset the results", "name": "offset", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" } ], "responses": { "200": { "description": "Playbook data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/PlaybookData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "active": { "type": "boolean", "default": true }, "type": { "type": "string", "nullable": true, "enum": [ "LEGACY", "SECTOR", "SOLUTION", "MILESTONE", "PRACTITIONER", "COMPETITIVE", "ACCOUNT", "CUSTOM", null ] }, "framework": { "type": "string", "nullable": true, "enum": [ "CVI_WHY_CHANGE", null ] }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ], "default": "active" }, "referenceMode": { "type": "string", "enum": [ "specific", "none" ], "default": "specific" }, "proofPointMode": { "type": "string", "enum": [ "specific", "none" ], "default": "none" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "product": { "$ref": "#/components/schemas/PlaybookProduct" }, "service": { "$ref": "#/components/schemas/PlaybookService" }, "buyerPersonas": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookPersona" } }, "useCases": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookUseCase" } }, "references": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookReference" } }, "segment": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } }, "competitor": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } }, "proofPoints": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } } } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } }, "total": { "type": "number", "description": "Total number of playbooks" } }, "required": [ "_metadata", "data", "total" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/playbook/create": { "post": { "deprecated": false, "operationId": "createPlaybook", "summary": "Create Playbook", "description": "Create Playbook", "tags": [ "Playbook" ], "x-visibility": "public", "requestBody": { "description": "Playbook creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "Name of the playbook" }, "description": { "type": "string", "description": "Description of the playbook" }, "keyInsight": { "type": "string", "description": "Key insight of the playbook" }, "type": { "type": "string", "description": "Type of the playbook. Legacy types are automatically mapped: SEGMENT\u2192SECTOR, SIGNAL\u2192MILESTONE, SPECIALIST\u2192PRACTITIONER." }, "context": { "type": "string", "description": "Context of the playbook - used to help select Personas and Use Cases if none are provided" }, "personaOIds": { "type": "array", "items": { "type": "string" }, "description": "Persona OIds of the playbook" }, "useCaseOIds": { "type": "array", "items": { "type": "string" }, "description": "Use case OIds of the playbook" }, "competitorOId": { "type": "string", "description": "Competitor OId for competitive playbooks" }, "segmentOId": { "type": "string", "description": "Segment OId of the playbook" }, "proofPointOIds": { "type": "array", "items": { "type": "string" }, "description": "Proof point OIds of the playbook" }, "referenceOIds": { "type": "array", "items": { "type": "string" }, "description": "Reference OIds of the playbook" }, "productOId": { "type": "string", "description": "@deprecated Use `offeringOId` instead. Kept for backward compatibility.", "deprecated": true }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated playbook", "example": "bv_123456" }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ], "default": "active", "description": "Status of the playbook", "example": "active" }, "referenceMode": { "type": "string", "enum": [ "specific", "none" ], "default": "specific", "description": "Reference mode of the playbook", "example": "specific" }, "proofPointMode": { "type": "string", "enum": [ "specific", "none" ], "default": "none", "description": "Proof point mode of the playbook", "example": "none" }, "additionalContextSources": { "$ref": "#/components/schemas/additionalContextSources" }, "async": { "type": "boolean", "default": false, "description": "If true, the playbook creation will be processed asynchronously. The API will return immediately with a message indicating the request has been queued.", "example": false }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. When provided with async: true, the API will POST the result to this URL once processing completes.", "example": "https://example.com/webhook/playbook" }, "offeringOId": { "type": "string", "description": "Workspace offering OId for the playbook. Accepts Product and Service OIds only (Solution is not supported)." } }, "required": [ "description", "keyInsight" ] } } } }, "responses": { "200": { "description": "Playbook data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "playbook": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "type": { "type": "string", "nullable": true, "enum": [ "LEGACY", "SECTOR", "SOLUTION", "MILESTONE", "PRACTITIONER", "COMPETITIVE", "ACCOUNT", "CUSTOM", null ] }, "keyInsight": { "type": "array", "items": { "type": "string" } } } }, "personas": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the persona", "example": "p_1234" }, "name": { "type": "string", "nullable": true, "description": "The name of the persona", "example": "VP of Sales" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the persona", "example": "Sally the Sales Leader" }, "description": { "type": "string", "nullable": true, "description": "The description of the persona" }, "active": { "type": "boolean", "default": true, "description": "Whether the persona is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/PersonaData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "valueProps": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "evidence": { "type": "array", "nullable": true, "items": { "type": "string" } } } } } }, "required": [ "oId", "data", "valueProps" ] } } }, "required": [ "_metadata", "playbook", "personas" ] } } } }, "400": { "description": "Bad request - Occurs with invalid input parameters, including when unsupported source types are provided (only URL and TEXT source types are supported)", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/playbook/update": { "post": { "deprecated": false, "operationId": "updatePlaybook", "summary": "Update Playbook", "description": "Update an existing playbook. Only provided fields will be updated - omitted fields remain unchanged. The 'data' object will be shallow merged with existing data.", "tags": [ "Playbook" ], "x-visibility": "public", "requestBody": { "description": "Playbook update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the playbook to update", "example": "pb_1234" }, "name": { "type": "string", "description": "The name of the playbook", "example": "Enterprise Sales Playbook" }, "description": { "type": "string", "description": "A description of the playbook", "example": "Comprehensive playbook for enterprise sales processes" }, "explanation": { "type": "string", "description": "Detailed explanation of the playbook strategy", "example": "This playbook focuses on enterprise accounts with complex decision-making processes" }, "attributes": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Key attributes and characteristics of the playbook", "example": { "industry": [ "technology", "healthcare" ], "size": [ "enterprise" ] } }, "keyInsight": { "type": "array", "items": { "type": "string" }, "description": "Key insights that drive this playbook strategy", "example": [ "Enterprise buyers value ROI demonstrations", "Decision process involves multiple stakeholders" ] }, "exampleDomains": { "type": "array", "items": { "type": "string" }, "description": "Example company domains that fit this playbook", "example": [ "acme.com", "example.com", "enterprise.com" ] }, "exampleDescription": { "type": "string", "description": "Example description or scenario for this playbook", "example": "Target Fortune 500 companies with existing CRM systems looking to modernize" }, "approachAngle": { "type": "array", "items": { "type": "string" }, "description": "Different angles or approaches for this playbook", "example": [ "ROI-focused approach", "Security-first messaging", "Integration benefits" ] }, "strategicNarrative": { "type": "array", "items": { "type": "string" }, "description": "Strategic narrative components for this playbook", "example": [ "Digital transformation is essential", "Legacy systems are holding you back" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional playbook information" } ] } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Playbook updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/PlaybookData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "active": { "type": "boolean", "default": true }, "type": { "type": "string", "nullable": true, "enum": [ "LEGACY", "SECTOR", "SOLUTION", "MILESTONE", "PRACTITIONER", "COMPETITIVE", "ACCOUNT", "CUSTOM", null ] }, "framework": { "type": "string", "nullable": true, "enum": [ "CVI_WHY_CHANGE", null ] }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ], "default": "active" }, "referenceMode": { "type": "string", "enum": [ "specific", "none" ], "default": "specific" }, "proofPointMode": { "type": "string", "enum": [ "specific", "none" ], "default": "none" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "product": { "$ref": "#/components/schemas/PlaybookProduct" }, "service": { "$ref": "#/components/schemas/PlaybookService" }, "buyerPersonas": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookPersona" } }, "useCases": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookUseCase" } }, "references": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookReference" } }, "segment": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } }, "competitor": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } }, "proofPoints": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } } } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Playbook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/playbook/delete": { "delete": { "deprecated": false, "operationId": "deletePlaybook", "summary": "Delete Playbook", "description": "Soft delete a Playbook by OId. The playbook will be marked as deleted but not permanently removed.", "tags": [ "Playbook" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Playbook OId" }, "required": true, "description": "Playbook OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted playbook data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "$ref": "#/components/schemas/PlaybookData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "active": { "type": "boolean", "default": true }, "type": { "type": "string", "nullable": true, "enum": [ "LEGACY", "SECTOR", "SOLUTION", "MILESTONE", "PRACTITIONER", "COMPETITIVE", "ACCOUNT", "CUSTOM", null ] }, "framework": { "type": "string", "nullable": true, "enum": [ "CVI_WHY_CHANGE", null ] }, "status": { "type": "string", "enum": [ "active", "draft", "archived" ], "default": "active" }, "referenceMode": { "type": "string", "enum": [ "specific", "none" ], "default": "specific" }, "proofPointMode": { "type": "string", "enum": [ "specific", "none" ], "default": "none" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "User first name" }, "lastName": { "type": "string", "nullable": true, "description": "User last name" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "product": { "$ref": "#/components/schemas/PlaybookProduct" }, "service": { "$ref": "#/components/schemas/PlaybookService" }, "buyerPersonas": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookPersona" } }, "useCases": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookUseCase" } }, "references": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/PlaybookReference" } }, "segment": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } }, "competitor": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } }, "proofPoints": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "data": { "nullable": true } } } } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Playbook not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/use-case/get": { "get": { "deprecated": false, "operationId": "getUseCase", "summary": "Get Use Case", "description": "Get Use Case by OId", "tags": [ "Use Case" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Use Case OId" }, "required": true, "description": "Use Case OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Use Case data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the use case", "example": "uc_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the use case was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was archived", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The name of the use case", "example": "Use Case Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the use case", "example": "Use Case Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the use case", "example": "Use Case Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the use case", "example": "https://www.use-case.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the use case is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/UseCaseData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the use case", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the use case", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" } }, "required": [ "_metadata", "oId", "createdAt", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Use Case not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/use-case/list": { "get": { "deprecated": false, "operationId": "listUseCases", "summary": "List Use Cases", "description": "List Use Cases", "tags": [ "Use Case" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "text", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Playbook OId" }, "required": false, "description": "Playbook OId", "name": "playbookOId", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" }, "description": "OIds", "example": [ "123", "456" ] }, "required": false, "description": "OIds", "name": "oIds", "in": "query" } ], "responses": { "200": { "description": "Use Case data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "total": { "type": "number", "description": "Total number of use cases" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the use case", "example": "uc_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the use case was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was archived", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The name of the use case", "example": "Use Case Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the use case", "example": "Use Case Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the use case", "example": "Use Case Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the use case", "example": "https://www.use-case.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the use case is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/UseCaseData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the use case", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the use case", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" } }, "required": [ "oId", "createdAt", "user", "workspace" ] } } }, "required": [ "_metadata", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/use-case/create": { "post": { "deprecated": false, "operationId": "createUseCase", "summary": "Create Use Case", "description": "Create a new use case", "tags": [ "Use Case" ], "x-visibility": "public", "requestBody": { "description": "Use case creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the use case", "example": "Lead Generation" }, "internalName": { "type": "string", "description": "The internal name of the use case", "example": "Lead Gen Process" }, "description": { "type": "string", "description": "A description of the use case", "example": "Automated lead generation and qualification process" }, "primaryUrl": { "type": "string", "format": "uri", "description": "The primary URL of the use case", "example": "https://www.example.com/lead-generation" }, "summary": { "type": "string", "description": "A brief summary of the use case", "example": "Streamlined lead capture and qualification" }, "scenarios": { "type": "array", "items": { "type": "string" }, "description": "Different scenarios where this use case applies", "example": [ "New prospect visits website", "Existing customer referral" ] }, "desiredOutcomes": { "type": "array", "items": { "type": "string" }, "description": "The desired outcomes from this use case", "example": [ "Qualified leads", "Reduced manual work", "Higher conversion" ] }, "businessDrivers": { "type": "array", "items": { "type": "string" }, "description": "Business drivers that motivate this use case", "example": [ "Need to scale sales", "Reduce acquisition costs" ] }, "strategicImpact": { "type": "array", "items": { "type": "string" }, "description": "The strategic, business-level benefit realized when this use case is solved well: quantifiable impact on revenue, cost, risk, and/or efficiency, and the broader value to the company.", "example": [ "Increased revenue growth", "Improved market positioning" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional use case information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this use case, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } }, "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating personas. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking this use case to offerings (products/services)" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Use case created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the use case", "example": "uc_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the use case was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was archived", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The name of the use case", "example": "Use Case Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the use case", "example": "Use Case Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the use case", "example": "Use Case Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the use case", "example": "https://www.use-case.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the use case is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/UseCaseData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the use case", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the use case", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" } }, "required": [ "oId", "createdAt", "user", "workspace" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/use-case/update": { "post": { "deprecated": false, "operationId": "updateUseCase", "summary": "Update Use Case", "description": "Update an existing use case", "tags": [ "Use Case" ], "x-visibility": "public", "requestBody": { "description": "Use case update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the use case to update", "example": "uc_1234" }, "name": { "type": "string", "description": "The name of the use case", "example": "Lead Generation" }, "internalName": { "type": "string", "description": "The internal name of the use case", "example": "Lead Gen Process" }, "description": { "type": "string", "description": "A description of the use case", "example": "Automated lead generation and qualification process" }, "primaryUrl": { "type": "string", "format": "uri", "description": "The primary URL of the use case", "example": "https://www.example.com/lead-generation" }, "summary": { "type": "string", "description": "A brief summary of the use case", "example": "Streamlined lead capture and qualification" }, "scenarios": { "type": "array", "items": { "type": "string" }, "description": "Different scenarios where this use case applies", "example": [ "New prospect visits website", "Existing customer referral" ] }, "desiredOutcomes": { "type": "array", "items": { "type": "string" }, "description": "The desired outcomes from this use case", "example": [ "Qualified leads", "Reduced manual work", "Higher conversion" ] }, "businessDrivers": { "type": "array", "items": { "type": "string" }, "description": "Business drivers that motivate this use case", "example": [ "Need to scale sales", "Reduce acquisition costs" ] }, "strategicImpact": { "type": "array", "items": { "type": "string" }, "description": "The strategic, business-level benefit realized when this use case is solved well: quantifiable impact on revenue, cost, risk, and/or efficiency, and the broader value to the company.", "example": [ "Increased revenue growth", "Improved market positioning" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional use case information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this use case, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Use case updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the use case", "example": "uc_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the use case was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was archived", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The name of the use case", "example": "Use Case Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the use case", "example": "Use Case Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the use case", "example": "Use Case Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the use case", "example": "https://www.use-case.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the use case is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/UseCaseData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the use case", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the use case", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" } }, "required": [ "oId", "createdAt", "user", "workspace" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Use case not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/use-case/generate": { "post": { "deprecated": false, "operationId": "generateUseCases", "summary": "Generate Use Cases", "description": "Generate use cases from source materials using AI. Each input array generates one use case. Supports text, URLs, and generative names as sources.", "tags": [ "Use Case" ], "x-visibility": "public", "requestBody": { "description": "Use case generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating use cases. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated use cases", "example": "bv_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking generated use cases to offerings (products/services)" } ] }, "useCases": { "$ref": "#/components/schemas/UseCaseGenerationInputs" } }, "required": [ "useCases" ] } } } }, "responses": { "200": { "description": "Use cases generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the use case", "example": "uc_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the use case was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was archived", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The name of the use case", "example": "Use Case Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the use case", "example": "Use Case Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the use case", "example": "Use Case Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the use case", "example": "https://www.use-case.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the use case is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/UseCaseData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the use case", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the use case", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" } }, "required": [ "oId", "createdAt", "user", "workspace" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/use-case/delete": { "delete": { "deprecated": false, "operationId": "deleteUseCase", "summary": "Delete Use Case", "description": "Soft delete a Use Case by OId. The use case will be marked as deleted but not permanently removed.", "tags": [ "Use Case" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Use Case OId" }, "required": true, "description": "Use Case OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted use case data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the use case", "example": "uc_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the use case was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the use case was archived", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The name of the use case", "example": "Use Case Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the use case", "example": "Use Case Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the use case", "example": "Use Case Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the use case", "example": "https://www.use-case.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the use case is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/UseCaseData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "User OId" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the use case", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the use case", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "Workspace OId" } } }, "scenarios": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Scenarios" }, "desiredOutcomes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Desired Outcomes" } }, "required": [ "_metadata", "oId", "createdAt", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Use Case not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/reference/get": { "get": { "deprecated": false, "operationId": "getReference", "summary": "Get Reference", "description": "Get Reference by OId", "tags": [ "Reference" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Reference OId" }, "required": true, "description": "Reference OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Reference data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the reference", "example": "r_1234" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the reference", "example": "Large filesharing service" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the reference", "example": "Dropbox" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the reference was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was archived", "example": "2021-01-01" }, "description": { "type": "string", "nullable": true, "description": "The description of the reference", "example": "Description of the reference" }, "active": { "type": "boolean", "default": true, "description": "Whether the reference is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ReferenceData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the reference", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the reference", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace", "example": "w_1234" } } }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the reference is unrecognized", "example": false } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Reference not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/reference/list": { "get": { "deprecated": false, "operationId": "listReferences", "summary": "List References", "description": "List References", "tags": [ "Reference" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Text to search for" }, "required": false, "description": "Text to search for", "name": "text", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit the number of results" }, "required": false, "description": "Limit the number of results", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset the results" }, "required": false, "description": "Offset the results", "name": "offset", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Playbook OId" }, "required": false, "description": "Playbook OId", "name": "playbookOId", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" }, "description": "OIds" }, "required": false, "description": "OIds", "name": "oIds", "in": "query" } ], "responses": { "200": { "description": "Reference data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the reference", "example": "r_1234" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the reference", "example": "Large filesharing service" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the reference", "example": "Dropbox" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the reference was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was archived", "example": "2021-01-01" }, "description": { "type": "string", "nullable": true, "description": "The description of the reference", "example": "Description of the reference" }, "active": { "type": "boolean", "default": true, "description": "Whether the reference is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ReferenceData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the reference", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the reference", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace", "example": "w_1234" } } }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the reference is unrecognized", "example": false } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } }, "total": { "type": "number", "description": "Total number of results" } }, "required": [ "_metadata", "data", "total" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/reference/create": { "post": { "deprecated": false, "operationId": "createReference", "summary": "Create Reference", "description": "Create a new customer reference", "tags": [ "Reference" ], "x-visibility": "public", "requestBody": { "description": "Reference creation data", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The external facing name of the reference", "example": "Large filesharing service" }, "internalName": { "type": "string", "description": "The internal name of the reference", "example": "Dropbox" }, "description": { "type": "string", "description": "A description of the reference", "example": "Leading cloud storage and file sharing company" }, "data": { "allOf": [ { "$ref": "#/components/schemas/ReferenceData" }, { "description": "Additional reference data" } ] }, "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when creating reference. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking this reference to offerings (products/services)" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Reference created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the reference", "example": "r_1234" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the reference", "example": "Large filesharing service" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the reference", "example": "Dropbox" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the reference was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was archived", "example": "2021-01-01" }, "description": { "type": "string", "nullable": true, "description": "The description of the reference", "example": "Description of the reference" }, "active": { "type": "boolean", "default": true, "description": "Whether the reference is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ReferenceData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the reference", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the reference", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace", "example": "w_1234" } } }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the reference is unrecognized", "example": false } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } }, "required": [ "_metadata", "data" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/reference/update": { "post": { "deprecated": false, "operationId": "updateReference", "summary": "Update Reference", "description": "Update an existing reference", "tags": [ "Reference" ], "x-visibility": "public", "requestBody": { "description": "Reference update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the reference to update", "example": "ref_1234" }, "name": { "type": "string", "description": "The name of the reference", "example": "Acme Corporation" }, "internalName": { "type": "string", "description": "The internal name of the reference", "example": "Acme Corp (Internal)" }, "description": { "type": "string", "description": "A description of the reference", "example": "Leading technology company that achieved 50% growth using our solution" }, "businessModel": { "type": "array", "items": { "type": "string" }, "description": "How the customer operates commercially: revenue model, pricing structure, sales motion, and commercial dynamics.", "example": [ "SaaS platform with subscription revenue model", "Mid-market sales motion with annual contracts" ] }, "theirChallenge": { "type": "array", "items": { "type": "string" }, "description": "What was broken before they came to us \u2014 the pain, what they had tried that didn't work, and what triggered them to look for a better way.", "example": [ "Manual onboarding bottlenecks were capping new-customer growth.", "Internal scripts kept breaking under load and tying up CS bandwidth." ] }, "howTheyUseUs": { "type": "array", "items": { "type": "string" }, "description": "What they use us for in practice \u2014 which offerings they've adopted, how they've embedded them into their workflows, and the role we now play in their day-to-day operations.", "example": [ "Uses our API to integrate with their customer onboarding flow.", "Runs nightly reconciliation through our reporting pipeline." ] }, "whyTheyChoseUs": { "type": "array", "items": { "type": "string" }, "description": "The decision rationale: alternatives they considered, what made our offering stand out, and the specific factors that tipped them toward us.", "example": [ "Chose us for the API depth and real-time event streaming the others lacked.", "Existing team expertise made our SDK the lowest-friction path to production." ] }, "impactTheySaw": { "type": "array", "items": { "type": "string" }, "description": "The meaningful change attributable to working with us \u2014 qualitative shifts in their business and quantifiable metrics (when available). The 'before vs. after' story told with both narrative and numbers.", "example": [ "Reduced customer onboarding time by 60%", "Improved customer satisfaction by 25%", "Cut operational costs by 30%" ] }, "stakeholdersInvolved": { "type": "array", "items": { "type": "string" }, "description": "Roles, titles, and personas at the customer who drove and championed the work, and why they cared about this problem.", "example": [ "VP of Customer Success \u2014 owned the onboarding KPI and championed the rollout.", "Head of Engineering \u2014 needed an API-first solution that wouldn't bottleneck the dev team." ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional reference information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this reference, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Reference updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the reference", "example": "r_1234" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the reference", "example": "Large filesharing service" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the reference", "example": "Dropbox" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the reference was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was archived", "example": "2021-01-01" }, "description": { "type": "string", "nullable": true, "description": "The description of the reference", "example": "Description of the reference" }, "active": { "type": "boolean", "default": true, "description": "Whether the reference is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ReferenceData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the reference", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the reference", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace", "example": "w_1234" } } }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the reference is unrecognized", "example": false } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Reference not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/reference/generate": { "post": { "deprecated": false, "operationId": "generateReferences", "summary": "Generate References", "description": "Generate customer references from source materials using AI. Each input array generates one reference. Supports text, URLs, and generative names as sources.", "tags": [ "Reference" ], "x-visibility": "public", "requestBody": { "description": "Reference generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating references. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking generated references to offerings (products/services)" } ] }, "references": { "$ref": "#/components/schemas/ReferenceGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated references", "example": "bv_123456" } }, "required": [ "references" ] } } } }, "responses": { "200": { "description": "References generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the reference", "example": "r_1234" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the reference", "example": "Large filesharing service" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the reference", "example": "Dropbox" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the reference was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was archived", "example": "2021-01-01" }, "description": { "type": "string", "nullable": true, "description": "The description of the reference", "example": "Description of the reference" }, "active": { "type": "boolean", "default": true, "description": "Whether the reference is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ReferenceData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the reference", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the reference", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace", "example": "w_1234" } } }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the reference is unrecognized", "example": false } }, "required": [ "oId", "createdAt", "data", "user", "workspace" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/reference/delete": { "delete": { "deprecated": false, "operationId": "deleteReference", "summary": "Delete Reference", "description": "Soft delete a Reference by OId. The reference will be marked as deleted but not permanently removed.", "tags": [ "Reference" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Reference OId" }, "required": true, "description": "Reference OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted reference data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the reference", "example": "r_1234" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the reference", "example": "Large filesharing service" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the reference", "example": "Dropbox" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the reference was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was updated", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was deleted", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the reference was archived", "example": "2021-01-01" }, "description": { "type": "string", "nullable": true, "description": "The description of the reference", "example": "Description of the reference" }, "active": { "type": "boolean", "default": true, "description": "Whether the reference is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ReferenceData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the reference", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the reference", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace", "example": "w_1234" } } }, "unrecognized": { "type": "boolean", "nullable": true, "description": "Whether the reference is unrecognized", "example": false } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Reference not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/product/get": { "get": { "deprecated": false, "operationId": "getProduct", "summary": "Get Product", "description": "Get Product by OId", "tags": [ "Product" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Product OId" }, "required": true, "description": "Product OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Product data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the product", "example": "p_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the product was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the product was updated", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the product was archived", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the product was deleted", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the product", "example": "Product Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the product", "example": "Product Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the product", "example": "Product Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the product", "example": "https://www.product.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the product is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ProductData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the product", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the product", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the product", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the product belongs to", "example": "wa_1234" } } } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/product/list": { "get": { "deprecated": false, "operationId": "listProducts", "summary": "List Products", "description": "Lists product-table rows by default (`type=PRODUCT`). With `type=ALL`, returns products, services, and solutions in one paginated result (see response schema).", "tags": [ "Product" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Text" }, "required": false, "description": "Text", "name": "text", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "When `type=ALL`, restricts the combined list to rows whose `oId` is in this filter. Accepts Product, Service, or Solution OIds (each table is queried with the same id). When `type` is `PRODUCT` or `SERVICE`, only the product table is queried, so Service-table-only and Solution OIds typically return no rows." }, "required": false, "description": "When `type=ALL`, restricts the combined list to rows whose `oId` is in this filter. Accepts Product, Service, or Solution OIds (each table is queried with the same id). When `type` is `PRODUCT` or `SERVICE`, only the product table is queried, so Service-table-only and Solution OIds typically return no rows.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Same semantics as `offeringOId` (alias for backward compatibility).", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Same semantics as `offeringOId` (alias for backward compatibility).", "name": "productOId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ] }, { "type": "string", "enum": [ "ALL" ] } ], "default": "PRODUCT", "description": "Filter by offering type (PRODUCT, SERVICE, or ALL). When ALL, responses include solutions. Defaults to PRODUCT for backwards compatibility.", "example": "PRODUCT" }, "required": false, "description": "Filter by offering type (PRODUCT, SERVICE, or ALL). When ALL, responses include solutions. Defaults to PRODUCT for backwards compatibility.", "name": "type", "in": "query" } ], "responses": { "200": { "description": "List of offerings: product-table rows when `type` is PRODUCT or SERVICE; products, services, and solutions when `type` is ALL.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "total": { "type": "number", "description": "Total matching rows (products only when type=PRODUCT or SERVICE; products, services, and solutions when type=ALL)." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OfferingListItem" }, "description": "When type is ALL, combined offerings (product, service, solution). Otherwise product-table rows with a discriminating type field." } }, "required": [ "_metadata", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/product/create": { "post": { "deprecated": false, "operationId": "createProduct", "summary": "Create Product", "description": "Create a new product", "tags": [ "Product" ], "x-visibility": "public", "requestBody": { "description": "Product creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The external name of the product", "example": "Marketing Automation Platform" }, "internalName": { "type": "string", "description": "The internal name of the product", "example": "MAP Product" }, "description": { "type": "string", "description": "A description of the product", "example": "A comprehensive marketing automation solution for businesses" }, "primaryUrl": { "type": "string", "format": "uri", "description": "The primary URL of the product", "example": "https://www.product.com" }, "summary": { "type": "string", "description": "A brief summary of the product", "example": "Enterprise-grade marketing automation" }, "distinctCapabilities": { "type": "array", "items": { "type": "string" }, "description": "What the product does at the functional level \u2014 outcome-oriented capabilities, not mechanisms (mechanisms live in keyFunctionality).", "example": [ "Email automation", "Lead scoring", "Campaign analytics" ] }, "keyFunctionality": { "type": "array", "items": { "type": "string" }, "description": "Specific, named, often branded components of the product worth highlighting \u2014 the 'how' behind the capabilities.", "example": [ "Smart Send Time", "Predictive Lead Scoring", "Journey Builder" ] }, "differentiatedValue": { "type": "array", "items": { "type": "string" }, "description": "The differentiated value of the product", "example": [ "AI-powered personalization", "Advanced segmentation" ] }, "statusQuo": { "type": "array", "items": { "type": "string" }, "description": "The current state or status quo that the product addresses", "example": [ "Manual email campaigns", "Generic messaging" ] }, "challengesAddressed": { "type": "array", "items": { "type": "string" }, "description": "The challenges addressed by the offering", "example": [ "Low email engagement", "Poor lead qualification" ] }, "customerBenefits": { "type": "array", "items": { "type": "string" }, "description": "The customer benefits of the offering", "example": [ "Increased conversion rates", "Time savings" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional product information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this product, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Product created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/product/update": { "post": { "deprecated": false, "operationId": "updateProduct", "summary": "Update Product", "description": "Update an existing product", "tags": [ "Product" ], "x-visibility": "public", "requestBody": { "description": "Product update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the product to update", "example": "px_1234" }, "name": { "type": "string", "description": "The external name of the product", "example": "Marketing Automation Platform" }, "internalName": { "type": "string", "description": "The internal name of the product", "example": "MAP Product" }, "description": { "type": "string", "description": "A description of the product", "example": "A comprehensive marketing automation solution for businesses" }, "primaryUrl": { "type": "string", "format": "uri", "description": "The primary URL of the product", "example": "https://www.product.com" }, "type": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ], "description": "The type of offering", "example": "PRODUCT" }, "summary": { "type": "string", "description": "A brief summary of the product", "example": "Enterprise-grade marketing automation" }, "distinctCapabilities": { "type": "array", "items": { "type": "string" }, "description": "What the product does at the functional level \u2014 outcome-oriented capabilities, not mechanisms (mechanisms live in keyFunctionality).", "example": [ "Email automation", "Lead scoring", "Campaign analytics" ] }, "keyFunctionality": { "type": "array", "items": { "type": "string" }, "description": "Specific, named, often branded components of the product worth highlighting \u2014 the 'how' behind the capabilities.", "example": [ "Smart Send Time", "Predictive Lead Scoring", "Journey Builder" ] }, "differentiatedValue": { "type": "array", "items": { "type": "string" }, "description": "The differentiated value of the product", "example": [ "AI-powered personalization", "Advanced segmentation" ] }, "statusQuo": { "type": "array", "items": { "type": "string" }, "description": "The current state or status quo that the product addresses", "example": [ "Manual email campaigns", "Generic messaging" ] }, "challengesAddressed": { "type": "array", "items": { "type": "string" }, "description": "The challenges addressed by the offering", "example": [ "Low email engagement", "Poor lead qualification" ] }, "customerBenefits": { "type": "array", "items": { "type": "string" }, "description": "The customer benefits of the offering", "example": [ "Increased conversion rates", "Time savings" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional product information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this product, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Product updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/product/generate": { "post": { "deprecated": false, "operationId": "generateProducts", "summary": "Generate Product", "description": "Generate a product from source materials using AI. Creates and validates the product against usage rules.", "tags": [ "Product" ], "x-visibility": "public", "requestBody": { "description": "Product generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "products": { "$ref": "#/components/schemas/ProductGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Optional brand voice ID to apply to generated products", "example": "bv_789" }, "async": { "type": "boolean", "description": "If true, the product generation will be processed asynchronously", "example": false }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. When provided with async: true, the API will POST the result to this URL once processing completes.", "example": "https://example.com/webhook/product" } }, "required": [ "products" ] } } } }, "responses": { "200": { "description": "Product generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources, usage limit exceeded, or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/product/delete": { "delete": { "deprecated": false, "operationId": "deleteProduct", "summary": "Delete Product", "description": "Soft delete a Product by OId. The product will be marked as deleted but not permanently removed.", "tags": [ "Product" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Product OId" }, "required": true, "description": "Product OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted product data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the product", "example": "p_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the product was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the product was updated", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the product was archived", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the product was deleted", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the product", "example": "Product Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the product", "example": "Product Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the product", "example": "Product Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the product", "example": "https://www.product.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the product is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ProductData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the product", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the product", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the product", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the product belongs to", "example": "wa_1234" } } } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Product not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/service/get": { "get": { "deprecated": false, "operationId": "getService", "summary": "Get Service", "description": "Get Service by OId", "tags": [ "Service" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Service OId" }, "required": true, "description": "Service OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Service data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the service", "example": "p_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the service was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the service was updated", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the service was archived", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the service was deleted", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the service", "example": "Service Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the service", "example": "Service Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the service", "example": "Service Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the service", "example": "https://www.service.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the service is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ServiceData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the service", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the service", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the service", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the service belongs to", "example": "wa_1234" } } } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Service not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/service/list": { "get": { "deprecated": false, "operationId": "listServices", "summary": "List Services", "description": "List Services", "tags": [ "Service" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "text", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Service OId" }, "required": false, "description": "Service OId", "name": "serviceOId", "in": "query" } ], "responses": { "200": { "description": "List of services", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "total": { "type": "number", "description": "Total number of services" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" }, "description": "List of services" } }, "required": [ "_metadata", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/service/create": { "post": { "deprecated": false, "operationId": "createService", "summary": "Create Service", "description": "Create a new service", "tags": [ "Service" ], "x-visibility": "public", "requestBody": { "description": "Service creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The external name of the service", "example": "Managed Analytics Onboarding" }, "internalName": { "type": "string", "description": "The internal name of the service", "example": "Analytics Onboarding Service" }, "description": { "type": "string", "description": "A description of the service", "example": "Hands-on onboarding engagement that configures and validates customer analytics dashboards" }, "primaryUrl": { "type": "string", "format": "uri", "description": "The primary URL of the service", "example": "https://www.example.com/services/onboarding" }, "summary": { "type": "string", "description": "A brief summary of the service", "example": "6-week onboarding engagement for enterprise customers" }, "deliverables": { "type": "array", "items": { "type": "string" }, "description": "Key deliverables of the service", "example": [ "Onboarding plan", "Integration runbook", "Training session" ] }, "competencies": { "type": "array", "items": { "type": "string" }, "description": "Key competencies required for the service", "example": [ "Data engineering", "Customer success" ] }, "comparativeAdvantage": { "type": "array", "items": { "type": "string" }, "description": "The comparative advantage of the service", "example": [ "Faster time to value", "Dedicated success engineer" ] }, "likelyAlternative": { "type": "array", "items": { "type": "string" }, "description": "The likely alternative to the service", "example": [ "In-house rollout", "Generalist consulting firm" ] }, "challengesAddressed": { "type": "array", "items": { "type": "string" }, "description": "The challenges addressed by the service", "example": [ "Slow time to insight", "Ad-hoc data pipelines" ] }, "customerBenefits": { "type": "array", "items": { "type": "string" }, "description": "The customer benefits of the service", "example": [ "Reliable reporting", "Reduced internal engineering load" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional service information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this service, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Service created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Service" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/service/update": { "post": { "deprecated": false, "operationId": "updateService", "summary": "Update Service", "description": "Update an existing service", "tags": [ "Service" ], "x-visibility": "public", "requestBody": { "description": "Service update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the service to update", "example": "sc_1234" }, "name": { "type": "string", "description": "The external name of the service", "example": "Managed Analytics Onboarding" }, "internalName": { "type": "string", "description": "The internal name of the service", "example": "Analytics Onboarding Service" }, "description": { "type": "string", "description": "A description of the service", "example": "Hands-on onboarding engagement that configures and validates customer analytics dashboards" }, "primaryUrl": { "type": "string", "format": "uri", "description": "The primary URL of the service", "example": "https://www.example.com/services/onboarding" }, "summary": { "type": "string", "description": "A brief summary of the service", "example": "6-week onboarding engagement for enterprise customers" }, "deliverables": { "type": "array", "items": { "type": "string" }, "description": "Key deliverables of the service", "example": [ "Onboarding plan", "Integration runbook", "Training session" ] }, "competencies": { "type": "array", "items": { "type": "string" }, "description": "Key competencies required for the service", "example": [ "Data engineering", "Customer success" ] }, "comparativeAdvantage": { "type": "array", "items": { "type": "string" }, "description": "The comparative advantage of the service", "example": [ "Faster time to value", "Dedicated success engineer" ] }, "likelyAlternative": { "type": "array", "items": { "type": "string" }, "description": "The likely alternative to the service", "example": [ "In-house rollout", "Generalist consulting firm" ] }, "challengesAddressed": { "type": "array", "items": { "type": "string" }, "description": "The challenges addressed by the service", "example": [ "Slow time to insight", "Ad-hoc data pipelines" ] }, "customerBenefits": { "type": "array", "items": { "type": "string" }, "description": "The customer benefits of the service", "example": [ "Reliable reporting", "Reduced internal engineering load" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional service information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this service, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Service updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Service" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Service not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/service/generate": { "post": { "deprecated": false, "operationId": "generateServices", "summary": "Generate Service", "description": "Generate a service from source materials using AI. Creates and validates the service against usage rules.", "tags": [ "Service" ], "x-visibility": "public", "requestBody": { "description": "Service generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "$ref": "#/components/schemas/ServiceGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Optional brand voice ID to apply to generated services", "example": "bv_789" } }, "required": [ "services" ] } } } }, "responses": { "200": { "description": "Service generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources, usage limit exceeded, or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/service/delete": { "post": { "deprecated": false, "operationId": "deleteService", "summary": "Delete Service", "description": "Soft delete a Service by OId. The service will be marked as deleted but not permanently removed.", "tags": [ "Service" ], "x-visibility": "public", "requestBody": { "description": "Service delete input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "Service OId" } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Deleted service data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the service", "example": "p_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the service was created", "example": "2021-01-01" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the service was updated", "example": "2021-01-01" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the service was archived", "example": "2021-01-01" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the service was deleted", "example": "2021-01-01" }, "name": { "type": "string", "nullable": true, "description": "The external facing name of the service", "example": "Service Name" }, "internalName": { "type": "string", "nullable": true, "description": "The internal name of the service", "example": "Service Internal Name" }, "description": { "type": "string", "nullable": true, "description": "The description of the service", "example": "Service Description" }, "primaryUrl": { "type": "string", "nullable": true, "description": "The primary URL of the service", "example": "https://www.service.com" }, "active": { "type": "boolean", "default": true, "description": "Whether the service is active and can be used", "example": true }, "data": { "$ref": "#/components/schemas/ServiceData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the user who created the service", "example": "u_1234" }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the service", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the service", "example": "Doe" } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true, "description": "The ID of the workspace that the service belongs to", "example": "wa_1234" } } } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Service not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/solution/get": { "get": { "deprecated": false, "operationId": "getSolution", "summary": "Get Solution", "description": "Get Solution by OId", "tags": [ "Solution" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Solution OId" }, "required": true, "description": "Solution OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Solution data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the solution", "example": "sv_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the solution was created" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "primaryUrl": { "type": "string", "nullable": true, "description": "Primary website URL for the solution, when available from sources" }, "active": { "type": "boolean", "default": true }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "data": { "$ref": "#/components/schemas/SolutionPersistedData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true } } }, "linkedProducts": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true }, "offeringType": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ] } }, "required": [ "oId", "offeringType" ] }, "default": [] }, "linkedUseCases": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "default": [] }, "linkedPersonas": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "default": [] }, "linkedSegments": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "default": [] }, "locked": { "type": "boolean" }, "lockedBy": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "picture": { "type": "string" } }, "required": [ "oId" ] } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace", "locked" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Solution not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/solution/list": { "get": { "deprecated": false, "operationId": "listSolutions", "summary": "List Solutions", "description": "List solutions in the workspace", "tags": [ "Solution" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Text to search for" }, "required": false, "description": "Text to search for", "name": "text", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit the number of results" }, "required": false, "description": "Limit the number of results", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset the results" }, "required": false, "description": "Offset the results", "name": "offset", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": true, "description": "Only return active solutions" }, "required": false, "description": "Only return active solutions", "name": "activeOnly", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by a single offering OId (solution)" }, "required": false, "description": "Filter by a single offering OId (solution)", "name": "offeringOId", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by offering OIds (solutions)" }, "required": false, "description": "Filter by offering OIds (solutions)", "name": "offeringOIds", "in": "query" } ], "responses": { "200": { "description": "Solutions list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Solution" }, { "type": "object", "properties": { "locked": { "type": "boolean" }, "lockedBy": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "picture": { "type": "string" } }, "required": [ "oId" ] } }, "required": [ "locked" ] } ] } }, "total": { "type": "number", "description": "Total number of solutions matching the query" } }, "required": [ "_metadata", "data", "total" ] } } } } } } }, "/api/v2/solution/create": { "post": { "deprecated": false, "operationId": "createSolution", "summary": "Create Solution", "description": "Create a new solution from generated output and sources", "tags": [ "Solution" ], "x-visibility": "public", "requestBody": { "description": "Solution creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "solution": { "$ref": "#/components/schemas/GeneratedSolutionOutput" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "GOOGLE_DRIVE_FILE_ID", "GENERATIVE_NAME", "OID", "COMPANY_NAME", "FIELDWISE_DOCUMENT_ID", "RAG_DOCUMENT_ID", "RESOURCE", "REPORT", "REPORT_SECTION", "EVENT_OID_FINDINGS", "FINDING_OIDS" ] }, "value": { "type": "string" }, "name": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "useNameIfUrlFails": { "type": "boolean", "nullable": true } }, "required": [ "type", "value" ] } }, "active": { "type": "boolean" }, "enableRagEnrichment": { "type": "boolean" }, "offeringOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "useCaseOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "personaOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "segmentOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "referenceOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "collateralOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "competitorOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "alternativeOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "buyingTriggerOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "objectionOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "proofPointOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "genericTextEntityOIds": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "solution", "sources" ] } } } }, "responses": { "200": { "description": "Solution created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Solution" }, { "type": "object", "properties": { "locked": { "type": "boolean" }, "lockedBy": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "picture": { "type": "string" } }, "required": [ "oId" ] } }, "required": [ "locked" ] } ] } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/solution/update": { "post": { "deprecated": false, "operationId": "updateSolution", "summary": "Update Solution", "description": "Update an existing solution", "tags": [ "Solution" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "Solution OId" }, "data": { "type": "object", "properties": { "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "primaryUrl": { "type": "string", "nullable": true, "description": "Primary website URL for the solution, when available from sources" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "data": { "type": "object", "properties": { "internalName": { "type": "string", "nullable": true }, "summary": { "type": "string", "nullable": true }, "distinctCapabilities": { "type": "array", "items": { "type": "string" }, "default": [] }, "keyComponents": { "type": "array", "items": { "type": "string" }, "default": [] }, "customerBenefits": { "type": "array", "items": { "type": "string" }, "default": [] }, "challengesAddressed": { "type": "array", "items": { "type": "string" }, "default": [] }, "statusQuo": { "type": "array", "items": { "type": "string" }, "default": [] }, "differentiatedValue": { "type": "array", "items": { "type": "string" }, "default": [] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } }, "type": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ], "default": "SOLUTION" } } } }, "description": "Fields to update on the solution" }, "libraryLinks": { "$ref": "#/components/schemas/SolutionLibraryLinksChange" } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Solution updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "allOf": [ { "$ref": "#/components/schemas/Solution" }, { "type": "object", "properties": { "locked": { "type": "boolean" }, "lockedBy": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "picture": { "type": "string" } }, "required": [ "oId" ] } }, "required": [ "locked" ] } ] } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/solution/generate": { "post": { "deprecated": false, "operationId": "generateSolutions", "summary": "Generate Solution", "description": "Generate solution draft content from sources, name, optional library links, and instructions", "tags": [ "Solution" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the solution to generate", "example": "Enterprise Analytics Suite" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "GOOGLE_DRIVE_FILE_ID", "GENERATIVE_NAME", "OID", "COMPANY_NAME", "FIELDWISE_DOCUMENT_ID", "RAG_DOCUMENT_ID", "RESOURCE", "REPORT", "REPORT_SECTION", "EVENT_OID_FINDINGS", "FINDING_OIDS" ] }, "value": { "type": "string" }, "name": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "useNameIfUrlFails": { "type": "boolean", "nullable": true } }, "required": [ "type", "value" ] }, "description": "Source materials to generate the solution from" }, "instructions": { "type": "string", "description": "Optional additional instructions for generation" }, "brandVoiceOId": { "type": "string", "description": "Optional brand voice ID to apply to the generated solution", "example": "bv_789" }, "enableRagEnrichment": { "type": "boolean", "description": "Whether to enable RAG enrichment during generation" }, "save": { "type": "boolean", "description": "If true, the generated solution is persisted immediately. Returns the saved entity under `savedSolution` in the response.", "example": false }, "async": { "type": "boolean", "description": "If true, the solution generation will be processed asynchronously. Requires save: true to persist the result.", "example": false }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. When provided with async: true, the API will POST the result to this URL once processing completes.", "example": "https://example.com/webhook/solution" }, "offeringOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "useCaseOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "personaOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "segmentOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "referenceOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "collateralOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "competitorOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "alternativeOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "buyingTriggerOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "objectionOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "proofPointOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "genericTextEntityOIds": { "type": "array", "items": { "type": "string" }, "default": [] } }, "required": [ "name", "sources" ] } } } }, "responses": { "200": { "description": "Generated solution payload (not persisted)", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "allOf": [ { "$ref": "#/components/schemas/GeneratedSolutionOutput" }, { "type": "object", "properties": { "savedSolution": { "allOf": [ { "$ref": "#/components/schemas/Solution" }, { "type": "object", "properties": { "locked": { "type": "boolean" }, "lockedBy": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "picture": { "type": "string" } }, "required": [ "oId" ] } }, "required": [ "locked" ] } ], "description": "The persisted solution entity. Only present when the request was made with save: true." } } } ] } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/solution/delete": { "delete": { "deprecated": false, "operationId": "deleteSolution", "summary": "Delete Solution", "description": "Soft-delete a solution", "tags": [ "Solution" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Solution OId" }, "required": true, "description": "Solution OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Solution deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "minLength": 1, "description": "The ID of the solution", "example": "sv_1234" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time the solution was created" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "nullable": true }, "internalName": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "primaryUrl": { "type": "string", "nullable": true, "description": "Primary website URL for the solution, when available from sources" }, "active": { "type": "boolean", "default": true }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "data": { "$ref": "#/components/schemas/SolutionPersistedData" }, "user": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } } }, "workspace": { "type": "object", "properties": { "oId": { "type": "string", "nullable": true } } }, "linkedProducts": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true }, "offeringType": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ] } }, "required": [ "oId", "offeringType" ] }, "default": [] }, "linkedUseCases": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "default": [] }, "linkedPersonas": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "default": [] }, "linkedSegments": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "default": [] }, "locked": { "type": "boolean" }, "lockedBy": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "picture": { "type": "string" } }, "required": [ "oId" ] } }, "required": [ "_metadata", "oId", "createdAt", "data", "user", "workspace", "locked" ] } } } } } } }, "/api/v2/async/agent/run": { "post": { "deprecated": false, "operationId": "asyncRunAgent", "summary": "Run Agent", "description": "Asynchronously run agents", "tags": [ "Async" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Optional header used to identify the source of the request. Helps us apply appropriate rate limiting or disable it when necessary.", "example": "some-source" }, "required": false, "description": "Optional header used to identify the source of the request. Helps us apply appropriate rate limiting or disable it when necessary.", "name": "x-request-source", "in": "header" }, { "schema": { "type": "string", "description": "External Request ID. Add this header to identify the request from the client for better tracking and debugging.", "example": "external-request-id" }, "required": false, "description": "External Request ID. Add this header to identify the request from the client for better tracking and debugging.", "name": "x-external-request-id", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "companyDomain": { "type": "string", "nullable": true, "description": "Company domain to enrich", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name to enrich", "example": "Example" }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context", "example": { "user": { "oId": "user_123" } } }, "agentOId": { "type": "string", "description": "Agent OId", "example": "ca_..." }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead.", "example": "https://example.com/api/callbacks/unique-id" }, "experimentOId": { "type": "string", "description": "Experiment OId", "example": "ae_..." } }, "title": "Enrich Company" }, { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to enrich", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to enrich", "example": "John" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to enrich", "example": "Software Engineer" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain of the person to enrich" }, "companyName": { "type": "string", "nullable": true, "description": "Company name of the person to enrich", "example": "Example" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to enrich", "example": "https://www.linkedin.com/in/john-doe/" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context", "example": { "user": { "oId": "user_123" } } }, "agentOId": { "type": "string", "description": "Agent OId", "example": "ca_..." }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead.", "example": "https://example.com/api/callbacks/unique-id" }, "experimentOId": { "type": "string", "description": "Experiment OId", "example": "ae_..." } }, "title": "Enrich Person" }, { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to generate content for", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to generate content for" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to generate content for" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain to generate content for", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name to generate content for" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to generate content for" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context" }, "url": { "type": "string", "nullable": true, "description": "URL to generate content for" }, "customContext": { "type": "object", "nullable": true, "properties": { "playbook": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "product": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "service": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "persona": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "segment": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] } }, "description": "Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning).", "example": { "persona": { "oId": "pe_xxxxxxxxxxxxxxxxxxxxx" }, "segment": { "oId": "sg_xxxxxxxxxxxxxxxxxxxxx" } } }, "outputFormat": { "type": "string", "nullable": true, "enum": [ "JSON", "TEXT", "HTML", "MARKDOWN", null ] }, "agentOId": { "type": "string", "description": "Agent OId", "example": "ca_..." }, "experimentOId": { "type": "string", "description": "Experiment OId", "example": "ae_..." }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead.", "example": "https://example.com/api/callbacks/unique-id" } }, "title": "Content Agent", "required": [ "agentOId" ] }, { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to generate emails for", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to generate emails for" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to generate emails for" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain of the person to generate emails for", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name of the person to generate emails for" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to generate emails for" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "lang": { "type": "string", "nullable": true, "description": "Language of the person to generate emails for" }, "requestId": { "type": "string", "nullable": true }, "outputFormat": { "type": "string", "nullable": true, "enum": [ "text", "html", "markdown", null ], "default": "text", "description": "Output format of the emails to generate" }, "runtimeContext": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional context (facts, research, account data) injected at runtime to personalize the generated sequence. Keys control which email steps receive the context: \"all\" applies to every email, \"1\"-\"4\" apply to a specific step (1-based index). Step-specific context is merged with the \"all\" context.", "example": { "1": "Reference her AWS SCA leadership role in the opening.", "all": "Account research: NICE Ltd expanded their AI partner program from 25 to 200 partners. Sarah leads strategic alliances." } }, "runtimeInstructions": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Behavioral directives that control how the agent writes the sequence \u2014 tone, structure, emphasis, constraints. Keys work the same way as runtimeContext: \"all\" applies to every email, \"1\"-\"4\" apply to a specific step (1-based index). Use runtimeInstructions for writing style directives. Use runtimeContext for factual data.", "example": { "1": "Lead with a specific personal detail \u2014 do not open with a generic intro.", "all": "Keep emails under 150 words. Use a consultative tone, not salesy." } }, "playbookSelectionContext": { "type": "string", "nullable": true, "description": "Playbook selection context of the person to generate emails for" }, "customContext": { "type": "object", "nullable": true, "properties": { "playbook": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "product": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "service": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "persona": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] }, "segment": { "type": "object", "properties": { "oId": { "type": "string" } }, "required": [ "oId" ] } }, "description": "Pins specific library entities for this run, overriding the agent's configured selection. Each field takes the oId of an entity in your workspace, and that exact entity is used with no re-matching. On motion agents, playbook.oId must be an active motion playbook; if the agent is configured with a specific motion, the playbook must belong to that motion or the request fails with a 400. product/service pin the offering unless the resolved motion playbook supplies its own (reported as a run warning).", "example": { "persona": { "oId": "pe_xxxxxxxxxxxxxxxxxxxxx" }, "segment": { "oId": "sg_xxxxxxxxxxxxxxxxxxxxx" } } }, "fullSequenceMode": { "type": "boolean" }, "agentOId": { "type": "string", "description": "Agent OId", "example": "ca_..." }, "experimentOId": { "type": "string", "description": "Experiment OId", "example": "ae_..." }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead.", "example": "https://example.com/api/callbacks/unique-id" } }, "title": "Sequence Agent", "required": [ "agentOId" ] }, { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to qualify", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to qualify" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to qualify" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain of the person to qualify", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name of the person to qualify" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to qualify" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context for qualification" }, "agentOId": { "type": "string", "description": "Agent OId", "example": "ca_..." }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead.", "example": "https://example.com/api/callbacks/unique-id" }, "experimentOId": { "type": "string", "description": "Experiment OId", "example": "ae_..." } }, "title": "Qualify Person Agent", "required": [ "agentOId" ] }, { "type": "object", "properties": { "companyDomain": { "type": "string", "description": "Company to find prospects or use as lookalike source", "example": "example.com" }, "limit": { "type": "number", "nullable": true, "description": "Override the Agent's configured limit", "example": 10, "minimum": 1, "maximum": 1000 }, "minimal": { "type": "boolean", "default": true, "description": "Minimize the output. If set to true, `positions`, `internalPictureUrl`, and the nested `company` object will be omitted from the output.", "example": true }, "searchContext": { "type": "object", "properties": { "playbookOId": { "type": "string", "nullable": true }, "personaOIds": { "type": "array", "nullable": true, "items": { "type": "string" } }, "fuzzyTitles": { "type": "array", "nullable": true, "items": { "type": "string" } }, "exactTitles": { "type": "array", "nullable": true, "items": { "type": "string" } }, "excludeTitles": { "type": "array", "nullable": true, "items": { "type": "string" } }, "personCountry": { "type": "object", "nullable": true, "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } }, "personLocation": { "type": "object", "nullable": true, "properties": { "countryCode": { "type": "object", "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } }, "city": { "type": "object", "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } }, "text": { "type": "object", "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } } } } }, "description": "Optional search context to override agent's configured search context. If provided, the two objects will be merged." }, "agentOId": { "type": "string", "description": "Agent OId", "example": "ca_..." }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead.", "example": "https://example.com/api/callbacks/unique-id" }, "experimentOId": { "type": "string", "description": "Experiment OId", "example": "ae_..." } }, "required": [ "agentOId" ], "title": "Prospector Agent" }, { "type": "object", "properties": { "companyDomain": { "type": "string", "nullable": true, "description": "Company domain to qualify", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name to qualify" }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context for qualification" }, "agentOId": { "type": "string", "description": "Agent OId", "example": "ca_..." }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /async/agent/run/status with the returned requestId instead.", "example": "https://example.com/api/callbacks/unique-id" }, "experimentOId": { "type": "string", "description": "Experiment OId", "example": "ae_..." } }, "title": "Qualify Company Agent", "required": [ "agentOId" ] } ], "description": "Run agent by given input, the input is different for each agent", "oneOf": [ { "$ref": "#/components/schemas/EnrichCompanyAgentInput", "title": "Enrich Company" }, { "$ref": "#/components/schemas/EnrichPersonAgentInput", "title": "Enrich Person" }, { "$ref": "#/components/schemas/GenerateContentAgentInput", "title": "Content Agent" }, { "$ref": "#/components/schemas/SequenceAgentInput", "title": "Sequence Agent" }, { "$ref": "#/components/schemas/QualifyPersonAgentInput", "title": "Qualify Person Agent" }, { "$ref": "#/components/schemas/QualifyCompanyAgentInput", "title": "Qualify Company Agent" } ] } } } }, "responses": { "200": { "description": "Agent data", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "description": "Status", "example": "pending" }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "requestId": { "type": "string", "description": "Request ID", "example": "requestId" }, "agentOId": { "type": "string", "description": "The Agent OId that was selected/used for the run", "example": "ca_..." } }, "required": [ "status", "requestId" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "description": "Status", "example": "pending" }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "requestId": { "type": "string", "description": "Request ID", "example": "requestId" } }, "required": [ "status", "requestId" ] }, "example": { "status": "failed", "message": "Invalid callback URL", "requestId": "123e4567-e89b-12d3-a456-426614174000" } } } }, "404": { "description": "Agent or other resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "description": "Status", "example": "pending" }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "requestId": { "type": "string", "description": "Request ID", "example": "requestId" } }, "required": [ "status", "requestId" ] }, "example": { "status": "failed", "message": "Agent or other resource not found", "requestId": "123e4567-e89b-12d3-a456-426614174000" } } } } } } }, "/api/v2/async/headless/generate-emails": { "post": { "deprecated": false, "operationId": "asyncGenerateEmails", "summary": "Generate Emails", "description": "Generate Emails asynchronously - Headless", "tags": [ "Async" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Optional header used to identify the source of the request. Helps us apply appropriate rate limiting or disable it when necessary.", "example": "some-source" }, "required": false, "description": "Optional header used to identify the source of the request. Helps us apply appropriate rate limiting or disable it when necessary.", "name": "x-request-source", "in": "header" }, { "schema": { "type": "string", "description": "External Request ID. Add this header to identify the request from the client for better tracking and debugging.", "example": "external-request-id" }, "required": false, "description": "External Request ID. Add this header to identify the request from the client for better tracking and debugging.", "name": "x-external-request-id", "in": "header" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence": { "type": "object", "properties": { "steps": { "type": "integer", "minimum": 1, "maximum": 7, "description": "Number of steps in the sequence", "example": 4 }, "length": { "type": "string", "enum": [ "SHORT", "MEDIUM", "LONG", "MIXED" ], "description": "Average length of emails in the sequence", "example": "MIXED" }, "type": { "type": "string", "enum": [ "COLD_OUTBOUND", "WARM_OUTBOUND", "INBOUND", "CUSTOM", "CVI_WHY_CHANGE", "BARE_METAL" ], "description": "Purpose of the sequence", "example": "COLD_OUTBOUND" }, "primaryGoal": { "type": "string", "enum": [ "INITIATE_CONVERSATION", "SCHEDULE_MEETING", "REQUEST_INTRODUCTION", "ASK_FOR_FEEDBACK", "FIND_TIME_TO_CONNECT", "POLITELY_DISENGAGE", "SMART_CTA" ], "description": "Primary goal for the sequence", "example": "INITIATE_CONVERSATION" }, "generateUniqueSubjectLines": { "type": "boolean", "description": "When true, generates unique subject lines for each email. When false reuse the first subject line for all subsequent emails.", "example": true }, "additionalInstructions": { "type": "string", "description": "Additional instructions for the sequence", "example": "Additional instructions for the sequence" }, "exampleForIntroEmail": { "type": "string", "description": "Example email for the first email in the sequence", "example": "Example email for the first email in the sequence" }, "exampleForFinalEmail": { "type": "string", "description": "Example email for the final email in the sequence", "example": "Example email for the final email in the sequence" }, "lang": { "type": "string", "description": "Target language for the generated emails. Recommended: Use ISO 639-1 language codes like 'es' (Spanish), 'fr' (French), 'de' (German), 'it' (Italian), 'pt' (Portuguese), 'ja' (Japanese), 'ko' (Korean). Full language names (e.g., 'spanish', 'french') are also supported for backward compatibility. Defaults to English ('en') if not specified.", "example": "es" }, "outputFormat": { "type": "string", "enum": [ "text", "html", "markdown" ], "description": "Output format for the generated emails (text, html, or markdown)", "example": "text" } }, "required": [ "steps" ] }, "offering": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Primary website for the Product/Service", "example": "https://www.example.com" }, "name": { "type": "string", "minLength": 1, "description": "External facing name of the Product or Service being offered", "example": "Example product/service" }, "coreValueProposition": { "nullable": true, "description": "Core value proposition of the offering. This helps ground the email sequence in the offering and provide a clear and concise message.", "example": "Example core value proposition" }, "keyDifferentiator": { "nullable": true, "description": "What makes this offering unique and different from the competition?", "example": "Example key differentiator" }, "customerOutcomes": { "nullable": true, "description": "What are the specific benefits and results that customers can expect from using this offering?", "example": "Example customer outcomes" }, "additionalOfferingInfo": { "nullable": true, "description": "Additional offer info", "example": "Example additional offer info" } }, "required": [ "url", "name" ] }, "recipient": { "type": "object", "properties": { "firstName": { "type": "string", "description": "Recipient's first name", "example": "John" }, "jobTitle": { "type": "string", "description": "Title", "example": "Example title" }, "linkedInProfile": { "type": "string", "format": "uri", "description": "LinkedIn profile", "example": "https://www.linkedin.com/in/example" }, "additionalRecipientInfo": { "type": "string", "description": "Additional recipient info", "example": "Example additional recipient info" }, "companyName": { "type": "string", "description": "Company name", "example": "Example company name" }, "companyDomain": { "type": "string", "description": "Company domain", "example": "example.com" } }, "required": [ "firstName", "companyName", "companyDomain" ] }, "callbackUrl": { "type": "string", "format": "uri", "description": "Callback URL", "example": "https://example.com/api/callbacks/unique-id" } }, "required": [ "sequence", "offering", "recipient", "callbackUrl" ] } } } }, "responses": { "200": { "description": "Async request accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "description": "Status", "example": "pending" }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "requestId": { "type": "string", "description": "Request ID", "example": "requestId" } }, "required": [ "status", "requestId" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "description": "Status", "example": "pending" }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "requestId": { "type": "string", "description": "Request ID", "example": "requestId" } }, "required": [ "status", "requestId" ] }, "example": { "status": "failed", "message": "Invalid callback URL", "requestId": "123e4567-e89b-12d3-a456-426614174000" } } } } } } }, "/api/v2/agents/workspace/build": { "post": { "deprecated": false, "operationId": "runWorkspaceBuilder", "summary": "Workspace Builder Agent", "description": "Generate and build a Workspace", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Generate and build a Workspace input", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the Workspace", "example": "Octave" }, "url": { "type": "string", "description": "URL of the Workspace", "example": "https://octave.com" }, "addExistingUsers": { "type": "boolean", "nullable": true, "default": true, "description": "If true, existing users of the parent workspace will be added to the new workspace", "example": true }, "agentOIds": { "type": "array", "items": { "type": "string" }, "description": "Optional array of agent OIds to copy from the source workspace", "example": [ "agent_oid1", "agent_oid2" ] } }, "required": [ "name", "url" ] }, "offering": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PRODUCT", "SERVICE", "SOLUTION" ], "description": "Type of offering - currently only PRODUCT is supported for workspace building.", "example": "PRODUCT" }, "name": { "type": "string", "nullable": true, "description": "Name of the Offering if different than the workspace", "example": "Octave" }, "additionalUrls": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Additional URLs for the Offering. By default the workspace URL will be used" }, "differentiatedValue": { "type": "string", "nullable": true, "description": "Differentiated Value of the Product", "example": "Our unique approach to..." }, "statusQuo": { "type": "string", "nullable": true, "description": "Status Quo of the Product" }, "comparativeAdvantage": { "type": "string", "nullable": true, "description": "Comparative Advantage of the Product", "example": "Our main advantage over the competition is..." }, "likelyAlternative": { "type": "string", "nullable": true, "description": "Likely Alternative of the Product", "example": "A more traditional approach to..." }, "references": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "url": { "type": "string", "nullable": true, "description": "URL of a case study or website of the reference customer" }, "details": { "type": "string", "nullable": true, "description": "Optional details of how the reference customer used or benefited from the offering" } } }, "description": "Optional array of existing reference customers that use the offering" } } }, "runtimeContext": { "nullable": true, "description": "Additional context to help build the Workspace, Persona, Use Cases, etc" }, "brandVoiceOId": { "type": "string", "description": "Optional brand voice ID to apply to generated entities", "example": "bv_789" }, "createDefaultAgents": { "type": "boolean", "description": "Whether to create default agents (Email, Prospector, etc.) for the new workspace", "example": true }, "async": { "type": "boolean", "description": "If true, the workspace build will be processed asynchronously", "example": false }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. When provided with async: true, the API will POST the result to this URL once processing completes.", "example": "https://example.com/webhook/workspace" } }, "required": [ "workspace" ] } } } }, "responses": { "200": { "description": "Workspace setup successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/WorkspaceBuilderData" } }, "required": [ "_metadata", "found" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/qualify-person/run": { "post": { "deprecated": false, "operationId": "runQualifyPersonAgent", "summary": "Qualify Person Agent", "description": "Determine if a person is qualified for a given Product, Persona, and/or Segment", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Qualify input", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to qualify", "example": "john.doe@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to qualify" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to qualify" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain of the person to qualify", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name of the person to qualify" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile of the person to qualify" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context for qualification" }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } }, "required": [ "agentOId" ] } } } }, "responses": { "200": { "description": "Qualification successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/QualifyPersonAgentData" } }, "required": [ "_metadata", "found" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/qualify-company/run": { "post": { "deprecated": false, "operationId": "runQualifyCompanyAgent", "summary": "Qualify Company Agent", "description": "Determine if a company is qualified for a given Product and/or Segment", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Qualify input", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyDomain": { "type": "string", "nullable": true, "description": "Company domain to qualify", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "Company name to qualify" }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context for qualification" }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } }, "required": [ "agentOId" ] } } } }, "responses": { "200": { "description": "Qualification successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/QualifyCompanyAgentData" } }, "required": [ "_metadata", "found" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/prospector/run": { "post": { "deprecated": false, "operationId": "runProspectorAgent", "summary": "Prospector Agent", "description": "Find relevant people at a company or lookalike companies", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Prospector input", "content": { "application/json": { "schema": { "type": "object", "properties": { "companyDomain": { "type": "string", "description": "Company to find prospects or use as lookalike source", "example": "example.com" }, "limit": { "type": "number", "nullable": true, "description": "Override the Agent's configured limit", "example": 10, "minimum": 1, "maximum": 1000 }, "minimal": { "type": "boolean", "default": true, "description": "Minimize the output. If set to true, `positions`, `internalPictureUrl`, and the nested `company` object will be omitted from the output.", "example": true }, "searchContext": { "type": "object", "properties": { "playbookOId": { "type": "string", "nullable": true }, "personaOIds": { "type": "array", "nullable": true, "items": { "type": "string" } }, "fuzzyTitles": { "type": "array", "nullable": true, "items": { "type": "string" } }, "exactTitles": { "type": "array", "nullable": true, "items": { "type": "string" } }, "excludeTitles": { "type": "array", "nullable": true, "items": { "type": "string" } }, "personCountry": { "type": "object", "nullable": true, "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } }, "personLocation": { "type": "object", "nullable": true, "properties": { "countryCode": { "type": "object", "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } }, "city": { "type": "object", "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } }, "text": { "type": "object", "properties": { "matches": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } }, "excludes": { "type": "object", "properties": { "exact": { "type": "array", "items": { "type": "string" } }, "contains": { "type": "array", "items": { "type": "string" } }, "prefix": { "type": "array", "items": { "type": "string" } } } } } } } } }, "description": "Optional search context to override agent's configured search context. If provided, the two objects will be merged." }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" } }, "required": [ "companyDomain", "agentOId" ] } } } }, "responses": { "200": { "description": "Prospector successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/ProspectorAgentData" } }, "required": [ "_metadata", "found" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/call-prep/run": { "post": { "deprecated": false, "operationId": "runCallPrepAgent", "summary": "Call Prep Agent", "description": "Generate call prep content including discovery questions, call scripts, and objection handling", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Call prep input", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "description": "Email of the person to build sales call prep materials for", "example": "john@example.com" }, "firstName": { "type": "string", "nullable": true, "description": "First name of the person to build sales call prep materials for" }, "lastName": { "type": "string", "nullable": true }, "jobTitle": { "type": "string", "nullable": true, "description": "Job title of the person to build sales call prep materials for" }, "companyDomain": { "type": "string", "nullable": true, "description": "The domain of the company to build call prep materials for", "example": "example.com" }, "companyName": { "type": "string", "nullable": true, "description": "The name of the company to build call prep materials for" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile URL of the person to build sales call prep materials for" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true }, "runtimeContext": { "nullable": true, "description": "Runtime context for sales call prep materials" }, "agentOId": { "type": "string", "description": "AgentOId is required when creating an agent in the application. You can find it in the Agents section of your dashboard.", "example": "agent_123" }, "includeFullAnnotation": { "type": "boolean", "description": "If true, returns full annotation data including metadata. If false or omitted (default), returns minimal annotations to reduce response size." } }, "required": [ "agentOId" ] } } } }, "responses": { "200": { "description": "Call prep successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/CallPrepAgentData" } }, "required": [ "_metadata", "found" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/experiment/create": { "post": { "deprecated": false, "operationId": "createAgentExperiment", "summary": "Create Agent Experiment", "description": "Create a new agent experiment", "tags": [ "Agents" ], "x-visibility": "public", "requestBody": { "description": "Agent experiment creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "agentType": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ] }, "runStrategy": { "type": "string", "enum": [ "RANDOM", "ROUND_ROBIN", "WEIGHTED" ] }, "agentOIds": { "type": "array", "items": { "type": "string" } }, "weights": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "oId", "weight" ] } } }, "required": [ "name", "agentType", "runStrategy", "agentOIds" ], "description": "Input for creating an agent experiment" } } } }, "responses": { "200": { "description": "Agent experiment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "agentType": { "type": "string", "enum": [ "PROSPECTOR", "CONTENT", "EMAIL", "ENRICH_PERSON", "ENRICH_COMPANY", "QUALIFY_PERSON", "QUALIFY_COMPANY", "CALL_PREP", "CONTEXT" ] }, "runStrategy": { "type": "string", "enum": [ "RANDOM", "ROUND_ROBIN", "WEIGHTED" ] }, "agents": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string" }, "costToRun": { "type": "number" } }, "required": [ "oId", "name" ] } }, "weights": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "oId": { "type": "string" }, "weight": { "type": "number" } }, "required": [ "oId", "weight" ] } }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "_metadata", "oId", "name", "agentType", "runStrategy", "agents", "createdAt", "updatedAt" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/competitor/get": { "get": { "deprecated": false, "operationId": "getCompetitor", "summary": "Get Competitor", "description": "Get Competitor by OId", "tags": [ "Competitor" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Competitor OId" }, "required": true, "description": "Competitor OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Competitor data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Competitor OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Competitor name" }, "internalName": { "type": "string", "description": "Competitor internal name" }, "description": { "type": "string", "nullable": true, "description": "Competitor description" }, "url": { "type": "string", "nullable": true, "description": "The competitor's canonical web URL (company homepage or product page), or null if unknown.", "example": "https://salesforce.com" }, "firmographics": { "type": "object", "nullable": true, "properties": { "overview": { "type": "string", "nullable": true }, "annualRecurringRevenueUsd": { "type": "number", "nullable": true, "minimum": 0 }, "annualRecurringRevenueEstimated": { "type": "boolean" }, "employeeCount": { "type": "integer", "nullable": true, "minimum": 0 }, "employeeCountEstimated": { "type": "boolean" }, "fundingTotalUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRound": { "type": "string", "nullable": true }, "latestFundingRoundAmountUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRoundDate": { "type": "string", "nullable": true }, "foundedYear": { "type": "integer", "nullable": true, "minimum": 1000, "maximum": 3000 }, "headquarters": { "type": "string", "nullable": true }, "marketSharePercent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "marketShareMarket": { "type": "string", "nullable": true }, "marketShareEstimated": { "type": "boolean" }, "websiteUrl": { "type": "string", "nullable": true, "format": "uri" }, "careersUrl": { "type": "string", "nullable": true, "format": "uri" }, "blogUrl": { "type": "string", "nullable": true, "format": "uri" }, "g2Url": { "type": "string", "nullable": true, "format": "uri" }, "citations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "researchedAt": { "type": "string", "format": "date-time" } }, "required": [ "overview", "annualRecurringRevenueUsd", "annualRecurringRevenueEstimated", "employeeCount", "employeeCountEstimated", "fundingTotalUsd", "latestFundingRound", "latestFundingRoundAmountUsd", "latestFundingRoundDate", "foundedYear", "headquarters", "marketSharePercent", "marketShareMarket", "marketShareEstimated", "websiteUrl", "careersUrl", "blogUrl", "g2Url", "citations", "researchedAt" ] }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/CompetitorData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the competitor", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the competitor", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/competitor/list": { "get": { "deprecated": false, "operationId": "listCompetitors", "summary": "List competitors", "description": "List competitors with optional filtering and pagination", "tags": [ "Competitor" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by competitor OIds" }, "required": false, "description": "Filter by competitor OIds", "name": "oIds", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "textSearchQuery", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Competitor list data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Competitor" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/competitor/generate": { "post": { "deprecated": false, "operationId": "generateCompetitors", "summary": "Generate Competitors", "description": "Generate competitor analysis from source materials using AI. Each input array generates one competitor analysis. Supports text, URLs, and generative names as sources.", "tags": [ "Competitor" ], "x-visibility": "public", "requestBody": { "description": "Competitor generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating competitors. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking generated competitors to offerings (products/services)" } ] }, "competitors": { "$ref": "#/components/schemas/CompetitorGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated competitors", "example": "bv_123456" } }, "required": [ "competitors" ] } } } }, "responses": { "200": { "description": "Competitors generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "firmographics": { "type": "object", "nullable": true, "properties": { "overview": { "type": "string", "nullable": true }, "annualRecurringRevenueUsd": { "type": "number", "nullable": true, "minimum": 0 }, "annualRecurringRevenueEstimated": { "type": "boolean" }, "employeeCount": { "type": "integer", "nullable": true, "minimum": 0 }, "employeeCountEstimated": { "type": "boolean" }, "fundingTotalUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRound": { "type": "string", "nullable": true }, "latestFundingRoundAmountUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRoundDate": { "type": "string", "nullable": true }, "foundedYear": { "type": "integer", "nullable": true, "minimum": 1000, "maximum": 3000 }, "headquarters": { "type": "string", "nullable": true }, "marketSharePercent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "marketShareMarket": { "type": "string", "nullable": true }, "marketShareEstimated": { "type": "boolean" }, "websiteUrl": { "type": "string", "nullable": true, "format": "uri" }, "careersUrl": { "type": "string", "nullable": true, "format": "uri" }, "blogUrl": { "type": "string", "nullable": true, "format": "uri" }, "g2Url": { "type": "string", "nullable": true, "format": "uri" }, "citations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "researchedAt": { "type": "string", "format": "date-time" } }, "required": [ "overview", "annualRecurringRevenueUsd", "annualRecurringRevenueEstimated", "employeeCount", "employeeCountEstimated", "fundingTotalUsd", "latestFundingRound", "latestFundingRoundAmountUsd", "latestFundingRoundDate", "foundedYear", "headquarters", "marketSharePercent", "marketShareMarket", "marketShareEstimated", "websiteUrl", "careersUrl", "blogUrl", "g2Url", "citations", "researchedAt" ] }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "howTheyPosition": { "type": "array", "items": { "type": "string" } }, "ourKeyDifferentiators": { "type": "array", "items": { "type": "string" } }, "competitorStrengths": { "type": "array", "items": { "type": "string" } }, "competitorWeaknesses": { "type": "array", "items": { "type": "string" } }, "reasonsWeWin": { "type": "array", "items": { "type": "string" } }, "reasonsWeLose": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "howTheyPosition", "ourKeyDifferentiators", "competitorStrengths", "competitorWeaknesses", "reasonsWeWin", "reasonsWeLose" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the competitor", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the competitor", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/competitor/create": { "post": { "deprecated": false, "operationId": "createCompetitor", "summary": "Create Competitor", "description": "Create a new competitor", "tags": [ "Competitor" ], "x-visibility": "public", "requestBody": { "description": "Competitor creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The external name of the competitor", "example": "Salesforce" }, "internalName": { "type": "string", "description": "The internal name of the competitor", "example": "SFDC - The CRM Giant" }, "description": { "type": "string", "description": "A description of the competitor", "example": "Leading CRM platform with strong enterprise presence" }, "url": { "type": "string", "nullable": true, "description": "The competitor's canonical web URL \u2014 the company homepage, or the product page when the competitor is a product of a larger company. A bare domain is also accepted. Used to resolve the competitor's logo.", "example": "https://salesforce.com" }, "howTheyPosition": { "type": "array", "items": { "type": "string" }, "description": "How the competitor positions themselves: their narrative, messaging, and market story \u2014 the pitch they take to market.", "example": [ "Positions as the all-in-one CRM for enterprises.", "Frames AI as the core differentiator across every product line." ] }, "ourKeyDifferentiators": { "type": "array", "items": { "type": "string" }, "description": "Concrete, observable, tactical points of differentiation we lead with against this competitor.", "example": [ "Native event-driven sync with Postgres CDC.", "Built-in SOC2 audit reporting at no extra cost." ] }, "competitorStrengths": { "type": "array", "items": { "type": "string" }, "description": "Where this competitor genuinely excels.", "example": [ "Market leader", "Strong brand recognition", "Enterprise customer base" ] }, "competitorWeaknesses": { "type": "array", "items": { "type": "string" }, "description": "Where this competitor falls short.", "example": [ "Complex implementation", "High cost", "Poor customer support" ] }, "reasonsWeWin": { "type": "array", "items": { "type": "string" }, "description": "Key reasons why customers choose your solution over this competitor", "example": [ "Better pricing", "Easier implementation", "Superior customer support" ] }, "reasonsWeLose": { "type": "array", "items": { "type": "string" }, "description": "The deal-level dynamics for why customers might choose them when both are evaluated.", "example": [ "Existing Salesforce-heavy stack with deep org-wide adoption.", "Procurement preference for the incumbent vendor." ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional competitor information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this competitor, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } }, "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when creating competitors. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking this competitor to offerings (products/services)" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Competitor created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "firmographics": { "type": "object", "nullable": true, "properties": { "overview": { "type": "string", "nullable": true }, "annualRecurringRevenueUsd": { "type": "number", "nullable": true, "minimum": 0 }, "annualRecurringRevenueEstimated": { "type": "boolean" }, "employeeCount": { "type": "integer", "nullable": true, "minimum": 0 }, "employeeCountEstimated": { "type": "boolean" }, "fundingTotalUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRound": { "type": "string", "nullable": true }, "latestFundingRoundAmountUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRoundDate": { "type": "string", "nullable": true }, "foundedYear": { "type": "integer", "nullable": true, "minimum": 1000, "maximum": 3000 }, "headquarters": { "type": "string", "nullable": true }, "marketSharePercent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "marketShareMarket": { "type": "string", "nullable": true }, "marketShareEstimated": { "type": "boolean" }, "websiteUrl": { "type": "string", "nullable": true, "format": "uri" }, "careersUrl": { "type": "string", "nullable": true, "format": "uri" }, "blogUrl": { "type": "string", "nullable": true, "format": "uri" }, "g2Url": { "type": "string", "nullable": true, "format": "uri" }, "citations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "researchedAt": { "type": "string", "format": "date-time" } }, "required": [ "overview", "annualRecurringRevenueUsd", "annualRecurringRevenueEstimated", "employeeCount", "employeeCountEstimated", "fundingTotalUsd", "latestFundingRound", "latestFundingRoundAmountUsd", "latestFundingRoundDate", "foundedYear", "headquarters", "marketSharePercent", "marketShareMarket", "marketShareEstimated", "websiteUrl", "careersUrl", "blogUrl", "g2Url", "citations", "researchedAt" ] }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "howTheyPosition": { "type": "array", "items": { "type": "string" } }, "ourKeyDifferentiators": { "type": "array", "items": { "type": "string" } }, "competitorStrengths": { "type": "array", "items": { "type": "string" } }, "competitorWeaknesses": { "type": "array", "items": { "type": "string" } }, "reasonsWeWin": { "type": "array", "items": { "type": "string" } }, "reasonsWeLose": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "howTheyPosition", "ourKeyDifferentiators", "competitorStrengths", "competitorWeaknesses", "reasonsWeWin", "reasonsWeLose" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the competitor", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the competitor", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/competitor/update": { "post": { "deprecated": false, "operationId": "updateCompetitor", "summary": "Update Competitor", "description": "Update an existing competitor", "tags": [ "Competitor" ], "x-visibility": "public", "requestBody": { "description": "Competitor update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the competitor to update", "example": "cp_1234" }, "name": { "type": "string", "description": "The name of the competitor", "example": "Salesforce CRM" }, "internalName": { "type": "string", "description": "The internal name of the competitor", "example": "Salesforce (Main CRM Competitor)" }, "description": { "type": "string", "description": "A description of the competitor", "example": "Leading CRM platform with extensive enterprise features" }, "url": { "type": "string", "nullable": true, "description": "The competitor's canonical web URL \u2014 the company homepage, or the product page when the competitor is a product of a larger company. A bare domain is also accepted. Used to resolve the competitor's logo. Pass null to clear.", "example": "https://salesforce.com" }, "howTheyPosition": { "type": "array", "items": { "type": "string" }, "description": "How the competitor positions themselves: their narrative, messaging, and market story \u2014 the pitch they take to market.", "example": [ "Positions as the all-in-one CRM for enterprises.", "Frames AI as the core differentiator across every product line." ] }, "ourKeyDifferentiators": { "type": "array", "items": { "type": "string" }, "description": "Concrete, observable, tactical points of differentiation we lead with against this competitor \u2014 features, capabilities, integrations, certifications, IP, performance benchmarks, ecosystem advantages.", "example": [ "Native event-driven sync with Postgres CDC.", "Built-in SOC2 audit reporting at no extra cost." ] }, "competitorStrengths": { "type": "array", "items": { "type": "string" }, "description": "Where this competitor genuinely excels \u2014 capabilities, features, market position, brand recognition, ecosystem advantages.", "example": [ "Market leader", "Extensive integration ecosystem", "Strong brand recognition" ] }, "competitorWeaknesses": { "type": "array", "items": { "type": "string" }, "description": "Where this competitor falls short \u2014 gaps in their offering, capability holes, pricing rigidity, ecosystem limitations.", "example": [ "Complex setup", "High cost", "Steep learning curve" ] }, "reasonsWeWin": { "type": "array", "items": { "type": "string" }, "description": "Reasons why we win against this competitor", "example": [ "Lower cost", "Easier implementation", "Better customer support" ] }, "reasonsWeLose": { "type": "array", "items": { "type": "string" }, "description": "The deal-level dynamics for why customers might choose them when both are evaluated \u2014 the kinds of prospects, requirements, scenarios, or buyer types that favor them.", "example": [ "Existing Salesforce-heavy stack with deep org-wide adoption.", "Procurement preference for the incumbent vendor." ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional competitor information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this competitor, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Competitor updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "firmographics": { "type": "object", "nullable": true, "properties": { "overview": { "type": "string", "nullable": true }, "annualRecurringRevenueUsd": { "type": "number", "nullable": true, "minimum": 0 }, "annualRecurringRevenueEstimated": { "type": "boolean" }, "employeeCount": { "type": "integer", "nullable": true, "minimum": 0 }, "employeeCountEstimated": { "type": "boolean" }, "fundingTotalUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRound": { "type": "string", "nullable": true }, "latestFundingRoundAmountUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRoundDate": { "type": "string", "nullable": true }, "foundedYear": { "type": "integer", "nullable": true, "minimum": 1000, "maximum": 3000 }, "headquarters": { "type": "string", "nullable": true }, "marketSharePercent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "marketShareMarket": { "type": "string", "nullable": true }, "marketShareEstimated": { "type": "boolean" }, "websiteUrl": { "type": "string", "nullable": true, "format": "uri" }, "careersUrl": { "type": "string", "nullable": true, "format": "uri" }, "blogUrl": { "type": "string", "nullable": true, "format": "uri" }, "g2Url": { "type": "string", "nullable": true, "format": "uri" }, "citations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "researchedAt": { "type": "string", "format": "date-time" } }, "required": [ "overview", "annualRecurringRevenueUsd", "annualRecurringRevenueEstimated", "employeeCount", "employeeCountEstimated", "fundingTotalUsd", "latestFundingRound", "latestFundingRoundAmountUsd", "latestFundingRoundDate", "foundedYear", "headquarters", "marketSharePercent", "marketShareMarket", "marketShareEstimated", "websiteUrl", "careersUrl", "blogUrl", "g2Url", "citations", "researchedAt" ] }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "howTheyPosition": { "type": "array", "items": { "type": "string" } }, "ourKeyDifferentiators": { "type": "array", "items": { "type": "string" } }, "competitorStrengths": { "type": "array", "items": { "type": "string" } }, "competitorWeaknesses": { "type": "array", "items": { "type": "string" } }, "reasonsWeWin": { "type": "array", "items": { "type": "string" } }, "reasonsWeLose": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "howTheyPosition", "ourKeyDifferentiators", "competitorStrengths", "competitorWeaknesses", "reasonsWeWin", "reasonsWeLose" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the competitor", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the competitor", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Competitor not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/competitor/delete": { "delete": { "deprecated": false, "operationId": "deleteCompetitor", "summary": "Delete Competitor", "description": "Soft delete a Competitor by OId. The competitor will be marked as deleted but not permanently removed.", "tags": [ "Competitor" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Competitor OId" }, "required": true, "description": "Competitor OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted competitor data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Competitor OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Competitor name" }, "internalName": { "type": "string", "description": "Competitor internal name" }, "description": { "type": "string", "nullable": true, "description": "Competitor description" }, "url": { "type": "string", "nullable": true, "description": "The competitor's canonical web URL (company homepage or product page), or null if unknown.", "example": "https://salesforce.com" }, "firmographics": { "type": "object", "nullable": true, "properties": { "overview": { "type": "string", "nullable": true }, "annualRecurringRevenueUsd": { "type": "number", "nullable": true, "minimum": 0 }, "annualRecurringRevenueEstimated": { "type": "boolean" }, "employeeCount": { "type": "integer", "nullable": true, "minimum": 0 }, "employeeCountEstimated": { "type": "boolean" }, "fundingTotalUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRound": { "type": "string", "nullable": true }, "latestFundingRoundAmountUsd": { "type": "number", "nullable": true, "minimum": 0 }, "latestFundingRoundDate": { "type": "string", "nullable": true }, "foundedYear": { "type": "integer", "nullable": true, "minimum": 1000, "maximum": 3000 }, "headquarters": { "type": "string", "nullable": true }, "marketSharePercent": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100 }, "marketShareMarket": { "type": "string", "nullable": true }, "marketShareEstimated": { "type": "boolean" }, "websiteUrl": { "type": "string", "nullable": true, "format": "uri" }, "careersUrl": { "type": "string", "nullable": true, "format": "uri" }, "blogUrl": { "type": "string", "nullable": true, "format": "uri" }, "g2Url": { "type": "string", "nullable": true, "format": "uri" }, "citations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "researchedAt": { "type": "string", "format": "date-time" } }, "required": [ "overview", "annualRecurringRevenueUsd", "annualRecurringRevenueEstimated", "employeeCount", "employeeCountEstimated", "fundingTotalUsd", "latestFundingRound", "latestFundingRoundAmountUsd", "latestFundingRoundDate", "foundedYear", "headquarters", "marketSharePercent", "marketShareMarket", "marketShareEstimated", "websiteUrl", "careersUrl", "blogUrl", "g2Url", "citations", "researchedAt" ] }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/CompetitorData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the competitor", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the competitor", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Competitor not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/alternative/get": { "get": { "deprecated": false, "operationId": "getAlternative", "summary": "Get Alternative", "description": "Get Alternative by OId", "tags": [ "Alternative" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Alternative OId" }, "required": true, "description": "Alternative OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Alternative data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Alternative OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Alternative name" }, "internalName": { "type": "string", "description": "Alternative internal name" }, "description": { "type": "string", "nullable": true, "description": "Alternative description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/AlternativeData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the alternative", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the alternative", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/alternative/list": { "get": { "deprecated": false, "operationId": "listAlternatives", "summary": "List alternatives", "description": "List alternatives with optional filtering and pagination", "tags": [ "Alternative" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by alternative OIds" }, "required": false, "description": "Filter by alternative OIds", "name": "oIds", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "textSearchQuery", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Alternative list data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Alternative" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/alternative/generate": { "post": { "deprecated": false, "operationId": "generateAlternatives", "summary": "Generate Alternatives", "description": "Generate status quo / incumbent alternative analysis from source materials using AI.", "tags": [ "Alternative" ], "x-visibility": "public", "requestBody": { "description": "Alternative generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating alternatives. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking generated alternatives to offerings (products/services)" } ] }, "alternatives": { "$ref": "#/components/schemas/AlternativeGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated alternatives", "example": "bv_123456" } }, "required": [ "alternatives" ] } } } }, "responses": { "200": { "description": "Alternatives generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "whereItWorks": { "type": "array", "items": { "type": "string" } }, "whereItBreaks": { "type": "array", "items": { "type": "string" } }, "whoChampionsThisApproach": { "type": "array", "items": { "type": "string" } }, "whyOurApproachIsSuperior": { "type": "array", "items": { "type": "string" } }, "perceivedBenefits": { "type": "array", "items": { "type": "string" } }, "hiddenCostsAndPitfalls": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whereItWorks", "whereItBreaks", "whoChampionsThisApproach", "whyOurApproachIsSuperior", "perceivedBenefits", "hiddenCostsAndPitfalls" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the alternative", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the alternative", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/alternative/create": { "post": { "deprecated": false, "operationId": "createAlternative", "summary": "Create Alternative", "description": "Create a new alternative (status quo / incumbent / DIY pattern)", "tags": [ "Alternative" ], "x-visibility": "public", "requestBody": { "description": "Alternative creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The external name of the status quo / incumbent alternative", "example": "Manual spreadsheet workflow" }, "internalName": { "type": "string", "description": "The internal name of the alternative", "example": "Excel + email research stack" }, "description": { "type": "string", "description": "A description of the alternative", "example": "Prospects stitch together spreadsheets and email to track outreach" }, "whereItWorks": { "type": "array", "items": { "type": "string" }, "description": "Conditions and contexts where this alternative genuinely holds up", "example": [ "Small team with one owner", "Low deal volume" ] }, "whereItBreaks": { "type": "array", "items": { "type": "string" }, "description": "Concrete failure modes and triggers where this approach stops working", "example": [ "Cross-team handoffs", "Compliance review" ] }, "whoChampionsThisApproach": { "type": "array", "items": { "type": "string" }, "description": "Personas or mindsets that advocate for this path and resist change", "example": [ "Frugal ops lead", "Founder who built the spreadsheet" ] }, "whyOurApproachIsSuperior": { "type": "array", "items": { "type": "string" }, "description": "Specific ways the offering addresses gaps and failure modes of this alternative", "example": [ "Single system of record", "Auditable workflow" ] }, "perceivedBenefits": { "type": "array", "items": { "type": "string" }, "description": "Why this approach feels rational, safe, or good enough organizationally", "example": [ "No new vendor risk", "Familiar tools" ] }, "hiddenCostsAndPitfalls": { "type": "array", "items": { "type": "string" }, "description": "Non-obvious costs, compounding debt, and second-order risks over time", "example": [ "Tribal knowledge loss", "Rework when owners rotate" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional alternative information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this alternative, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } }, "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when creating alternatives. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking this alternative to offerings (products/services)" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Alternative created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "whereItWorks": { "type": "array", "items": { "type": "string" } }, "whereItBreaks": { "type": "array", "items": { "type": "string" } }, "whoChampionsThisApproach": { "type": "array", "items": { "type": "string" } }, "whyOurApproachIsSuperior": { "type": "array", "items": { "type": "string" } }, "perceivedBenefits": { "type": "array", "items": { "type": "string" } }, "hiddenCostsAndPitfalls": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whereItWorks", "whereItBreaks", "whoChampionsThisApproach", "whyOurApproachIsSuperior", "perceivedBenefits", "hiddenCostsAndPitfalls" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the alternative", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the alternative", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/alternative/update": { "post": { "deprecated": false, "operationId": "updateAlternative", "summary": "Update Alternative", "description": "Update an existing alternative", "tags": [ "Alternative" ], "x-visibility": "public", "requestBody": { "description": "Alternative update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the alternative to update", "example": "ao_1234" }, "name": { "type": "string", "description": "The name of the alternative" }, "internalName": { "type": "string", "description": "The internal name of the alternative" }, "description": { "type": "string", "description": "A description of the alternative" }, "whereItWorks": { "type": "array", "items": { "type": "string" } }, "whereItBreaks": { "type": "array", "items": { "type": "string" } }, "whoChampionsThisApproach": { "type": "array", "items": { "type": "string" } }, "whyOurApproachIsSuperior": { "type": "array", "items": { "type": "string" } }, "perceivedBenefits": { "type": "array", "items": { "type": "string" } }, "hiddenCostsAndPitfalls": { "type": "array", "items": { "type": "string" } }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional alternative information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this alternative, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Alternative updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "whereItWorks": { "type": "array", "items": { "type": "string" } }, "whereItBreaks": { "type": "array", "items": { "type": "string" } }, "whoChampionsThisApproach": { "type": "array", "items": { "type": "string" } }, "whyOurApproachIsSuperior": { "type": "array", "items": { "type": "string" } }, "perceivedBenefits": { "type": "array", "items": { "type": "string" } }, "hiddenCostsAndPitfalls": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whereItWorks", "whereItBreaks", "whoChampionsThisApproach", "whyOurApproachIsSuperior", "perceivedBenefits", "hiddenCostsAndPitfalls" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the alternative", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the alternative", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Alternative not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/alternative/delete": { "delete": { "deprecated": false, "operationId": "deleteAlternative", "summary": "Delete Alternative", "description": "Soft delete a Alternative by OId. The alternative will be marked as deleted but not permanently removed.", "tags": [ "Alternative" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Alternative OId" }, "required": true, "description": "Alternative OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted alternative data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Alternative OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Alternative name" }, "internalName": { "type": "string", "description": "Alternative internal name" }, "description": { "type": "string", "nullable": true, "description": "Alternative description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/AlternativeData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the alternative", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the alternative", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Alternative not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/buying-trigger/get": { "get": { "deprecated": false, "operationId": "getBuyingTrigger", "summary": "Get Buying Trigger", "description": "Get buying trigger by OId", "tags": [ "Buying Trigger" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Buying trigger OId" }, "required": true, "description": "Buying trigger OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Buying trigger data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Buying trigger OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Buying trigger name" }, "internalName": { "type": "string", "description": "Buying trigger internal name" }, "description": { "type": "string", "nullable": true, "description": "Buying trigger description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/BuyingTriggerData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the buying trigger", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the buying trigger", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/buying-trigger/list": { "get": { "deprecated": false, "operationId": "listBuyingTriggers", "summary": "List buying triggers", "description": "List buying triggers with optional filtering and pagination", "tags": [ "Buying Trigger" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by buying trigger OIds" }, "required": false, "description": "Filter by buying trigger OIds", "name": "oIds", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "textSearchQuery", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Buying trigger list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BuyingTrigger" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/buying-trigger/generate": { "post": { "deprecated": false, "operationId": "generateBuyingTriggers", "summary": "Generate Buying Triggers", "description": "Generate buying trigger analysis from source materials using AI.", "tags": [ "Buying Trigger" ], "x-visibility": "public", "requestBody": { "description": "Buying trigger generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating buying triggers. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking generated buying triggers to offerings (products/services)" } ] }, "buyingTriggers": { "$ref": "#/components/schemas/BuyingTriggerGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated buying triggers", "example": "bv_123456" } }, "required": [ "buyingTriggers" ] } } } }, "responses": { "200": { "description": "Buying triggers generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "whyThisCreatesUrgency": { "type": "array", "items": { "type": "string" } }, "whoFeelsThisMost": { "type": "array", "items": { "type": "string" } }, "costOfInaction": { "type": "array", "items": { "type": "string" } }, "howWeHelpInThisMoment": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whyThisCreatesUrgency", "whoFeelsThisMost", "costOfInaction", "howWeHelpInThisMoment" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the buying trigger", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the buying trigger", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/buying-trigger/create": { "post": { "deprecated": false, "operationId": "createBuyingTrigger", "summary": "Create Buying Trigger", "description": "Create a new buying trigger", "tags": [ "Buying Trigger" ], "x-visibility": "public", "requestBody": { "description": "Buying trigger creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "External name of the buying trigger", "example": "New CIO cloud mandate" }, "internalName": { "type": "string", "description": "Internal name of the buying trigger" }, "description": { "type": "string", "description": "Description of the buying trigger" }, "whyThisCreatesUrgency": { "type": "array", "items": { "type": "string" }, "description": "Why this moment shifts the buyer from passive to active (one string per bullet)" }, "whoFeelsThisMost": { "type": "array", "items": { "type": "string" }, "description": "Which organizations and roles feel this trigger most (one string per bullet)" }, "costOfInaction": { "type": "array", "items": { "type": "string" }, "description": "Consequences of waiting while this trigger is in play (one string per bullet)" }, "howWeHelpInThisMoment": { "type": "array", "items": { "type": "string" }, "description": "Concrete ways the offering maps to this moment (one string per bullet)" }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this buying trigger, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } }, "primaryOfferingOId": { "type": "string", "description": "Primary offering for context when creating the entity (optional).", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking this buying trigger to offerings (products/services)" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Buying trigger created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "whyThisCreatesUrgency": { "type": "array", "items": { "type": "string" } }, "whoFeelsThisMost": { "type": "array", "items": { "type": "string" } }, "costOfInaction": { "type": "array", "items": { "type": "string" } }, "howWeHelpInThisMoment": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whyThisCreatesUrgency", "whoFeelsThisMost", "costOfInaction", "howWeHelpInThisMoment" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the buying trigger", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the buying trigger", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/buying-trigger/update": { "post": { "deprecated": false, "operationId": "updateBuyingTrigger", "summary": "Update Buying Trigger", "description": "Update an existing buying trigger", "tags": [ "Buying Trigger" ], "x-visibility": "public", "requestBody": { "description": "Buying trigger update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the buying trigger to update", "example": "btr_1234" }, "name": { "type": "string", "description": "The name of the buying trigger" }, "internalName": { "type": "string", "description": "The internal name of the buying trigger" }, "description": { "type": "string", "description": "A description of the buying trigger" }, "whyThisCreatesUrgency": { "type": "array", "items": { "type": "string" } }, "whoFeelsThisMost": { "type": "array", "items": { "type": "string" } }, "costOfInaction": { "type": "array", "items": { "type": "string" } }, "howWeHelpInThisMoment": { "type": "array", "items": { "type": "string" } }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional buying trigger information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this buying trigger, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Buying trigger updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "whyThisCreatesUrgency": { "type": "array", "items": { "type": "string" } }, "whoFeelsThisMost": { "type": "array", "items": { "type": "string" } }, "costOfInaction": { "type": "array", "items": { "type": "string" } }, "howWeHelpInThisMoment": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whyThisCreatesUrgency", "whoFeelsThisMost", "costOfInaction", "howWeHelpInThisMoment" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the buying trigger", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the buying trigger", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Buying trigger not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/buying-trigger/delete": { "delete": { "deprecated": false, "operationId": "deleteBuyingTrigger", "summary": "Delete Buying Trigger", "description": "Soft delete a buying trigger by OId. The buying trigger will be marked as deleted but not permanently removed.", "tags": [ "Buying Trigger" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Buying trigger OId" }, "required": true, "description": "Buying trigger OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted buying trigger data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Buying trigger OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Buying trigger name" }, "internalName": { "type": "string", "description": "Buying trigger internal name" }, "description": { "type": "string", "nullable": true, "description": "Buying trigger description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/BuyingTriggerData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the buying trigger", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the buying trigger", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Buying trigger not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/core-feature/get": { "get": { "deprecated": false, "operationId": "getCoreFeature", "summary": "Get Core Feature", "description": "Get Core Feature by OId", "tags": [ "Core Feature" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Core Feature OId" }, "required": true, "description": "Core Feature OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Core Feature data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Core Feature OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Core Feature name" }, "internalName": { "type": "string", "description": "Core Feature internal name" }, "description": { "type": "string", "nullable": true, "description": "Core Feature description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/CoreFeatureData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the core feature", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the core feature", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" }, "offering": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "type": { "type": "string", "enum": [ "product", "service", "solution" ] }, "name": { "type": "string", "nullable": true } }, "required": [ "oId", "type" ] } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/core-feature/list": { "get": { "deprecated": false, "operationId": "listCoreFeatures", "summary": "List core features", "description": "List core features with optional filtering and pagination", "tags": [ "Core Feature" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by core feature OIds" }, "required": false, "description": "Filter by core feature OIds", "name": "oIds", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by parent offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by parent offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by parent offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by parent offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "textSearchQuery", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Core Feature list data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CoreFeature" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/core-feature/generate": { "post": { "deprecated": false, "operationId": "generateCoreFeatures", "summary": "Generate Core Features", "description": "Generate named-capability core feature analysis from source materials using AI. Each generated core feature is attached to the provided parent offering.", "tags": [ "Core Feature" ], "x-visibility": "public", "requestBody": { "description": "Core Feature generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "minLength": 1, "description": "Parent Offering (Product, Service, or Solution) the generated core features belong to. A core feature must have exactly one parent offering, so this is required.", "example": "px_123456" }, "coreFeatures": { "$ref": "#/components/schemas/CoreFeatureGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated core features", "example": "bv_123456" } }, "required": [ "primaryOfferingOId", "coreFeatures" ] } } } }, "responses": { "200": { "description": "Core Features generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "whatItDoes": { "type": "array", "items": { "type": "string" } }, "howItWorks": { "type": "array", "items": { "type": "string" } }, "whatItImpacts": { "type": "array", "items": { "type": "string" } }, "whyThisExists": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whatItDoes", "howItWorks", "whatItImpacts", "whyThisExists" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the core feature", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the core feature", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "offering": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "type": { "type": "string", "enum": [ "product", "service", "solution" ] }, "name": { "type": "string", "nullable": true } }, "required": [ "oId", "type" ] } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/core-feature/create": { "post": { "deprecated": false, "operationId": "createCoreFeature", "summary": "Create Core Feature", "description": "Create a new core feature under a parent offering", "tags": [ "Core Feature" ], "x-visibility": "public", "requestBody": { "description": "Core Feature creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The external name of the core feature (named capability)", "example": "Real-time Deal Risk Alerts" }, "internalName": { "type": "string", "description": "The internal name of the core feature", "example": "Deal risk engine" }, "description": { "type": "string", "description": "A description of the core feature", "example": "Surfaces at-risk deals the moment engagement drops off" }, "whatItDoes": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities this feature delivers", "example": [ "Flags stalled deals", "Scores engagement decay" ] }, "howItWorks": { "type": "array", "items": { "type": "string" }, "description": "How the capability is delivered under the hood", "example": [ "Monitors activity signals", "Applies a decay model" ] }, "whatItImpacts": { "type": "array", "items": { "type": "string" }, "description": "Outcomes and metrics this feature moves", "example": [ "Win rate", "Forecast accuracy" ] }, "whyThisExists": { "type": "array", "items": { "type": "string" }, "description": "The problem or gap that justifies this feature", "example": [ "Reps miss silent churn signals" ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this core feature, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } }, "primaryOfferingOId": { "type": "string", "minLength": 1, "description": "Parent Offering (Product, Service, or Solution) this core feature belongs to. A core feature must have exactly one parent offering.", "example": "px_123456" } }, "required": [ "name", "primaryOfferingOId" ] } } } }, "responses": { "200": { "description": "Core Feature created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "whatItDoes": { "type": "array", "items": { "type": "string" } }, "howItWorks": { "type": "array", "items": { "type": "string" } }, "whatItImpacts": { "type": "array", "items": { "type": "string" } }, "whyThisExists": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whatItDoes", "howItWorks", "whatItImpacts", "whyThisExists" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the core feature", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the core feature", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "offering": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "type": { "type": "string", "enum": [ "product", "service", "solution" ] }, "name": { "type": "string", "nullable": true } }, "required": [ "oId", "type" ] } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/core-feature/update": { "post": { "deprecated": false, "operationId": "updateCoreFeature", "summary": "Update Core Feature", "description": "Update an existing core feature", "tags": [ "Core Feature" ], "x-visibility": "public", "requestBody": { "description": "Core Feature update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "Core Feature OId" }, "name": { "type": "string", "description": "The external name of the core feature" }, "internalName": { "type": "string", "description": "The internal name of the core feature" }, "description": { "type": "string", "description": "A description of the core feature" }, "whatItDoes": { "type": "array", "items": { "type": "string" }, "description": "Concrete capabilities this feature delivers" }, "howItWorks": { "type": "array", "items": { "type": "string" }, "description": "How the capability is delivered under the hood" }, "whatItImpacts": { "type": "array", "items": { "type": "string" }, "description": "Outcomes and metrics this feature moves" }, "whyThisExists": { "type": "array", "items": { "type": "string" }, "description": "The problem or gap that justifies this feature" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this core feature, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Core Feature updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "whatItDoes": { "type": "array", "items": { "type": "string" } }, "howItWorks": { "type": "array", "items": { "type": "string" } }, "whatItImpacts": { "type": "array", "items": { "type": "string" } }, "whyThisExists": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "whatItDoes", "howItWorks", "whatItImpacts", "whyThisExists" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the core feature", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the core feature", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "offering": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "type": { "type": "string", "enum": [ "product", "service", "solution" ] }, "name": { "type": "string", "nullable": true } }, "required": [ "oId", "type" ] } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Core Feature not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/core-feature/delete": { "delete": { "deprecated": false, "operationId": "deleteCoreFeature", "summary": "Delete Core Feature", "description": "Soft delete a Core Feature by OId. The core feature will be marked as deleted but not permanently removed.", "tags": [ "Core Feature" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Core Feature OId" }, "required": true, "description": "Core Feature OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted core feature data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Core Feature OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Core Feature name" }, "internalName": { "type": "string", "description": "Core Feature internal name" }, "description": { "type": "string", "nullable": true, "description": "Core Feature description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/CoreFeatureData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the core feature", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the core feature", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" }, "offering": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "type": { "type": "string", "enum": [ "product", "service", "solution" ] }, "name": { "type": "string", "nullable": true } }, "required": [ "oId", "type" ] } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Core Feature not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/objection/get": { "get": { "deprecated": false, "operationId": "getObjection", "summary": "Get Objection", "description": "Get objection by OId", "tags": [ "Objection" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Objection OId" }, "required": true, "description": "Objection OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Objection data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Objection OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Objection name" }, "internalName": { "type": "string", "description": "Objection internal name" }, "description": { "type": "string", "nullable": true, "description": "Objection description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/ObjectionData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the objection", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the objection", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/objection/list": { "get": { "deprecated": false, "operationId": "listObjections", "summary": "List objections", "description": "List objections with optional filtering and pagination", "tags": [ "Objection" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by objection OIds" }, "required": false, "description": "Filter by objection OIds", "name": "oIds", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution).", "deprecated": true }, "required": false, "description": "Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution).", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "textSearchQuery", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Objection list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Objection" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/objection/generate": { "post": { "deprecated": false, "operationId": "generateObjections", "summary": "Generate Objections", "description": "Generate objection handling content from source materials using AI.", "tags": [ "Objection" ], "x-visibility": "public", "requestBody": { "description": "Objection generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating objections. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking generated objections to offerings (products/services/solutions)" } ] }, "objections": { "$ref": "#/components/schemas/ObjectionGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated objections", "example": "bv_123456" } }, "required": [ "objections" ] } } } }, "responses": { "200": { "description": "Objections generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "underlyingConcern": { "type": "array", "items": { "type": "string" } }, "assumptionsAndMisconceptions": { "type": "array", "items": { "type": "string" } }, "areasToProbeAndClarify": { "type": "array", "items": { "type": "string" } }, "reframeAndResponse": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "underlyingConcern", "assumptionsAndMisconceptions", "areasToProbeAndClarify", "reframeAndResponse" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the objection", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the objection", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/objection/create": { "post": { "deprecated": false, "operationId": "createObjection", "summary": "Create Objection", "description": "Create a new objection", "tags": [ "Objection" ], "x-visibility": "public", "requestBody": { "description": "Objection creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "External name of the objection", "example": "Too expensive for our stage" }, "internalName": { "type": "string", "description": "Internal name of the objection" }, "description": { "type": "string", "description": "Description of the objection" }, "underlyingConcern": { "type": "array", "items": { "type": "string" }, "description": "What the buyer is really worried about (bullet strings)" }, "assumptionsAndMisconceptions": { "type": "array", "items": { "type": "string" }, "description": "Mistaken beliefs to address (bullet strings)" }, "areasToProbeAndClarify": { "type": "array", "items": { "type": "string" }, "description": "Discovery questions or topics to clarify" }, "reframeAndResponse": { "type": "array", "items": { "type": "string" }, "description": "How to reframe and respond (bullet strings)" }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this objection, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } }, "primaryOfferingOId": { "type": "string", "description": "Primary offering for context when creating the entity (optional).", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking this objection to offerings (products/services/solutions)" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Objection created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "underlyingConcern": { "type": "array", "items": { "type": "string" } }, "assumptionsAndMisconceptions": { "type": "array", "items": { "type": "string" } }, "areasToProbeAndClarify": { "type": "array", "items": { "type": "string" } }, "reframeAndResponse": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "underlyingConcern", "assumptionsAndMisconceptions", "areasToProbeAndClarify", "reframeAndResponse" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the objection", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the objection", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/objection/update": { "post": { "deprecated": false, "operationId": "updateObjection", "summary": "Update Objection", "description": "Update an existing objection", "tags": [ "Objection" ], "x-visibility": "public", "requestBody": { "description": "Objection update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the objection to update", "example": "oj_1234" }, "name": { "type": "string", "description": "The name of the objection" }, "internalName": { "type": "string", "description": "The internal name of the objection" }, "description": { "type": "string", "description": "A description of the objection" }, "underlyingConcern": { "type": "array", "items": { "type": "string" } }, "assumptionsAndMisconceptions": { "type": "array", "items": { "type": "string" } }, "areasToProbeAndClarify": { "type": "array", "items": { "type": "string" } }, "reframeAndResponse": { "type": "array", "items": { "type": "string" } }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional objection information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this objection, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Objection updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "underlyingConcern": { "type": "array", "items": { "type": "string" } }, "assumptionsAndMisconceptions": { "type": "array", "items": { "type": "string" } }, "areasToProbeAndClarify": { "type": "array", "items": { "type": "string" } }, "reframeAndResponse": { "type": "array", "items": { "type": "string" } }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "underlyingConcern", "assumptionsAndMisconceptions", "areasToProbeAndClarify", "reframeAndResponse" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the objection", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the objection", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Objection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/objection/delete": { "delete": { "deprecated": false, "operationId": "deleteObjection", "summary": "Delete Objection", "description": "Soft delete an objection by OId. The objection will be marked as deleted but not permanently removed.", "tags": [ "Objection" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Objection OId" }, "required": true, "description": "Objection OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted objection data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Objection OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Objection name" }, "internalName": { "type": "string", "description": "Objection internal name" }, "description": { "type": "string", "nullable": true, "description": "Objection description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/ObjectionData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the objection", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the objection", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Objection not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/segment/get": { "get": { "deprecated": false, "operationId": "getSegment", "summary": "Get Segment", "description": "Get Segment by OId", "tags": [ "Segment" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Segment OId" }, "required": true, "description": "Segment OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Segment data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Segment OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "description": "Segment name" }, "internalName": { "type": "string", "description": "Segment internal name" }, "description": { "type": "string", "nullable": true, "description": "Segment description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/SegmentData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] }, "description": "Qualifying questions" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the segment", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the segment", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" }, "unrecognized": { "type": "boolean" }, "rejected": { "type": "boolean" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "tagGroupOId": { "type": "string" }, "tagGroupName": { "type": "string" }, "tagOId": { "type": "string" }, "tagName": { "type": "string" } }, "required": [ "tagGroupOId", "tagGroupName", "tagOId", "tagName" ] } } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName", "unrecognized", "rejected" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/segment/list": { "get": { "deprecated": false, "operationId": "listSegments", "summary": "List segments", "description": "List segments with optional filtering and pagination", "tags": [ "Segment" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by segment OIds" }, "required": false, "description": "Filter by segment OIds", "name": "oIds", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "textSearchQuery", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Segment list data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/analytics/webhook/receive/generic/{eventType}": { "post": { "deprecated": false, "operationId": "logEvent", "summary": "Log Event", "description": "Log a custom event \u2014 emails, calls, CRM, and social data from your own integrations (n8n, Clay, Make, etc.) \u2014 into the analytics pipeline.\n\n## Event Types\n\nThe `{eventType}` path parameter determines the expected payload schema. Each event type has its own set of supported sub-types:\n\n### `emails` \u2014 Email Events\n\nSupported `eventType` values: `sent`, `reply`, `opened`, `clicked`, `bounced`, `unsubscribed`\n\n- Only **`sent`** and **`reply`** are processed for analytics; others are ingested but not processed.\n- Required fields: `eventTimestamp`, `eventType`, `subject`, `body` (text or html), `from`, `to`\n- Optional: `cc`, `bcc`, `eventId`, `conversationId`, `campaignId`, `customMetadata`\n\n### `calls` \u2014 Call/Meeting Events\n\nSupported `eventType` values: `transcript`, `scheduled`, `completed`, `missed`\n\n- Only **`transcript`** is processed for analytics; others are ingested but not processed.\n- Required fields: `eventTimestamp`, `eventType`, `title`, `transcript`, `participants`\n- Optional: `duration`, `recordingUrl`, `meetingPlatform`, `eventId`, `conversationId`, `customMetadata`\n- **Transcript formats:** Can be a flat string (LLM will diarize into speaker turns) or a structured array of entries with speaker attribution (recommended \u2014 faster and more reliable).\n\n### `crm` \u2014 CRM Events\n\nSupported `eventType` values: `opportunity_created`, `deal_won`, `deal_lost`, `meeting_booked`\n\n- All CRM event types are processed for analytics.\n- Required fields: `eventTimestamp`, `eventType`, `opportunityId`, `opportunityName`\n- Optional: `amount`, `stage`, `accountName`, `contactEmail`, `contactName`, `closeDate`, `customMetadata`\n\n### `social` \u2014 Social/LinkedIn Events\n\nSupported `eventType` values: `connection_sent`, `connection_accepted`, `message_sent`, `message_received`\n\n- All social event types are processed for analytics.\n- Required fields: `eventTimestamp`, `eventType`, `body` (text or html), `from`, `to`\n- Optional: `subject`, `eventId`, `conversationId`, `campaignId`, `messageType`, `campaignName`, `customMetadata`\n\n## Deduplication\n\nYou can provide an optional `eventId` field for explicit deduplication. If not provided, an ID is auto-generated from the event content:\n\n- **Emails:** `from_email + subject + timestamp + first_to_email`\n- **Calls:** `title + timestamp + first_participant + first_100_chars_transcript`\n- **CRM:** `opportunityId + eventType`\n- **Social:** auto-generated from content\n\n## Authentication\n\nWorkspace is identified by API key, passed as a query parameter (`api_key`) or in the request header.", "tags": [ "Events" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "enum": [ "emails", "calls", "crm", "social" ], "description": "Type of event being sent", "example": "emails" }, "required": true, "description": "Type of event being sent", "name": "eventType", "in": "path" }, { "schema": { "type": "string", "description": "Provide api key if not in header" }, "required": false, "description": "Provide api key if not in header", "name": "api_key", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "anyOf": [ { "allOf": [ { "$ref": "#/components/schemas/GenericEmailEvent" }, { "title": "Email Event", "example": { "eventTimestamp": "2024-02-03T10:30:00Z", "eventType": "sent", "subject": "Follow up on our conversation", "body": { "text": "Hi John, Just wanted to follow up on our call yesterday...", "html": "

Hi John,

Just wanted to follow up on our call yesterday...

" }, "from": { "email": "sarah@company.com", "name": "Sarah Johnson" }, "to": [ { "email": "john@prospect.com", "name": "John Smith" } ], "conversationId": "conv_abc123", "campaignId": "campaign_xyz" } } ] }, { "allOf": [ { "$ref": "#/components/schemas/GenericCallEvent" }, { "title": "Call Event", "example": { "eventTimestamp": "2024-02-03T14:00:00Z", "eventType": "transcript", "title": "Discovery Call - Acme Corp", "transcript": [ { "speaker": { "name": "Sarah Johnson", "email": "sarah@company.com", "role": "internal" }, "text": "Hi John, thanks for taking the time today. How are you doing?", "timestamp": "00:00:05" }, { "speaker": { "name": "John Smith", "email": "john@prospect.com", "role": "external" }, "text": "Good, thanks! Yeah, I was excited to learn more about what you all do.", "timestamp": "00:00:12" }, { "speaker": { "name": "Sarah Johnson", "email": "sarah@company.com", "role": "internal" }, "text": "Great! So I'd love to start by understanding a bit about your current setup...", "timestamp": "00:00:20" } ], "participants": [ { "email": "sarah@company.com", "name": "Sarah Johnson", "role": "internal" }, { "email": "john@prospect.com", "name": "John Smith", "role": "external" } ], "duration": 1800, "meetingPlatform": "zoom" } } ] }, { "allOf": [ { "$ref": "#/components/schemas/GenericCrmEvent" }, { "title": "CRM Event", "example": { "eventTimestamp": "2024-02-03T16:00:00Z", "eventType": "opportunity_created", "opportunityId": "opp_12345", "opportunityName": "Acme Corp - Enterprise Plan", "amount": 50000, "stage": "Qualification", "accountName": "Acme Corp", "contactEmail": "john@acme.com", "contactName": "John Smith", "closeDate": "2024-03-31T00:00:00Z" } } ] }, { "allOf": [ { "$ref": "#/components/schemas/GenericSocialEvent" }, { "title": "Social Event", "example": { "eventTimestamp": "2024-02-03T11:00:00Z", "eventType": "message_sent", "subject": "Introduction", "body": { "text": "Hi John, I came across your profile and would love to connect." }, "from": { "email": "sarah@company.com", "name": "Sarah Johnson" }, "to": [ { "email": "john@prospect.com", "name": "John Smith" } ], "conversationId": "conv_social_abc123", "campaignId": "campaign_linkedin_1", "messageType": "message", "campaignName": "Q1 Outreach" } } ] } ], "description": "Webhook payload. The schema depends on the `{eventType}` path parameter:\n- `emails` \u2014 Email Event schema\n- `calls` \u2014 Call Event schema\n- `crm` \u2014 CRM Event schema\n- `social` \u2014 Social Event schema (LinkedIn/social outreach)", "oneOf": [ { "$ref": "#/components/schemas/GenericEmailEvent", "title": "Email Event" }, { "$ref": "#/components/schemas/GenericCallEvent", "title": "Call Event" }, { "$ref": "#/components/schemas/GenericCrmEvent", "title": "CRM Event" }, { "$ref": "#/components/schemas/GenericSocialEvent", "title": "Social Event" } ] }, "examples": { "Email Event": { "summary": "Send an email event", "value": { "eventTimestamp": "2024-02-03T10:30:00Z", "eventType": "sent", "subject": "Follow up on our conversation", "body": { "text": "Hi John, Just wanted to follow up on our call yesterday...", "html": "

Hi John,

Just wanted to follow up on our call yesterday...

" }, "from": { "email": "sarah@company.com", "name": "Sarah Johnson" }, "to": [ { "email": "john@prospect.com", "name": "John Smith" } ], "conversationId": "conv_abc123", "campaignId": "campaign_xyz" } }, "Call Event (flat transcript)": { "summary": "Call with flat text transcript \u2014 LLM will diarize into speaker turns", "value": { "eventTimestamp": "2024-02-03T14:00:00Z", "eventType": "transcript", "title": "Discovery Call - Acme Corp", "transcript": "Sarah: Hi John, thanks for taking the time. John: Of course, happy to chat about your current setup...", "participants": [ { "email": "sarah@company.com", "name": "Sarah Johnson", "role": "internal" }, { "email": "john@prospect.com", "name": "John Smith", "role": "external" } ], "duration": 1800, "meetingPlatform": "zoom" } }, "Call Event (structured transcript)": { "summary": "Call with structured transcript entries \u2014 recommended, faster and more reliable", "value": { "eventTimestamp": "2024-02-03T14:00:00Z", "eventType": "transcript", "title": "Discovery Call - Acme Corp", "transcript": [ { "speaker": { "name": "Sarah Johnson", "email": "sarah@company.com", "role": "internal" }, "text": "Hi John, thanks for taking the time today. How are you doing?", "timestamp": "00:00:05" }, { "speaker": { "name": "John Smith", "email": "john@prospect.com", "role": "external" }, "text": "Good, thanks! Yeah, I was excited to learn more about what you all do.", "timestamp": "00:00:12" }, { "speaker": { "name": "Sarah Johnson", "email": "sarah@company.com", "role": "internal" }, "text": "Great! So I'd love to start by understanding a bit about your current setup...", "timestamp": "00:00:20" } ], "participants": [ { "email": "sarah@company.com", "name": "Sarah Johnson", "role": "internal" }, { "email": "john@prospect.com", "name": "John Smith", "role": "external" } ], "duration": 1800, "meetingPlatform": "zoom" } }, "CRM Event": { "summary": "Send a CRM opportunity event", "value": { "eventTimestamp": "2024-02-03T16:00:00Z", "eventType": "opportunity_created", "opportunityId": "opp_12345", "opportunityName": "Acme Corp - Enterprise Plan", "amount": 50000, "stage": "Qualification", "accountName": "Acme Corp", "contactEmail": "john@acme.com", "contactName": "John Smith", "closeDate": "2024-03-31T00:00:00Z" } }, "Social Event": { "summary": "Send a LinkedIn/social outreach event", "value": { "eventTimestamp": "2024-02-03T11:00:00Z", "eventType": "message_sent", "subject": "Introduction", "body": { "text": "Hi John, I came across your profile and would love to connect." }, "from": { "email": "sarah@company.com", "name": "Sarah Johnson" }, "to": [ { "email": "john@prospect.com", "name": "John Smith" } ], "conversationId": "conv_social_abc123", "campaignId": "campaign_linkedin_1", "messageType": "message", "campaignName": "Q1 Outreach" } } } } } }, "responses": { "200": { "description": "Webhook received successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "received": { "type": "boolean", "description": "Whether the payload was received" }, "additionalData": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Additional data about the processed event" }, "validationErrors": { "type": "object", "properties": { "fieldErrors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "formErrors": { "type": "array", "items": { "type": "string" } } }, "required": [ "fieldErrors", "formErrors" ], "description": "Per-field validation errors when the payload fails schema validation. Mirrors Zod's flatten() output so callers can map errors back to the offending fields." }, "connection": { "type": "object", "nullable": true, "properties": { "providerName": { "type": "string", "enum": [ "INSTANTLY", "FATHOM", "AMPERSAND_HUBSPOT", "AMPERSAND_SALESFORCE", "SMARTLEAD", "EMAILBISON", "FIREFLIES", "GONG", "CHORUS", "ORUM", "SALESFINITY", "OUTREACH", "OCTAVE_RESOURCES", "OCTAVE_REVISIONS", "SUPERSEND", "OCTAVE_GENERIC_EMAIL", "OCTAVE_GENERIC_CALL", "OCTAVE_GENERIC_CRM", "OCTAVE_GENERIC_SOCIAL", "CIRCLEBACK", "SYBILL", "GRANOLA", "SALESLOFT", "APOLLO", "HEYREACH", "GOOGLE_ADS", "META_ADS", "LINEAR", "ZOOM" ], "description": "Provider name for this event type" }, "shouldProcess": { "type": "boolean", "description": "Whether the payload should be processed" }, "connectionMethod": { "type": "string", "enum": [ "WEBHOOK", "CRON_JOB" ], "description": "Connection method" } }, "required": [ "providerName", "shouldProcess", "connectionMethod" ], "description": "Connection details" } }, "required": [ "_metadata", "received", "connection" ] } } } }, "400": { "description": "Bad request - invalid payload or event type", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Workspace not found or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/segment/generate": { "post": { "deprecated": false, "operationId": "generateSegments", "summary": "Generate Segments", "description": "Generate market segments from source materials using AI. Each input array generates one segment. Supports text, URLs, and generative names as sources.", "tags": [ "Segment" ], "x-visibility": "public", "requestBody": { "description": "Segment generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating segments. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking generated segments to offerings (products/services)" } ] }, "segments": { "$ref": "#/components/schemas/SegmentGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated segments", "example": "bv_123456" } }, "required": [ "segments" ] } } } }, "responses": { "200": { "description": "Segments generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "strategicFit": { "type": "array", "items": { "type": "string" }, "default": [] }, "firmographics": { "type": "object", "properties": { "industry": { "type": "array", "items": { "type": "string" }, "default": [] }, "businessModel": { "type": "array", "items": { "type": "string" }, "default": [] }, "geography": { "type": "array", "items": { "type": "string" }, "default": [] }, "revenue": { "type": "array", "items": { "type": "string" }, "default": [] }, "employees": { "type": "array", "items": { "type": "string" }, "default": [] } }, "default": { "industry": [], "businessModel": [], "geography": [], "revenue": [], "employees": [] }, "additionalProperties": { "nullable": true } }, "operatingCharacteristics": { "type": "array", "items": { "type": "string" }, "default": [] }, "strategicPriorities": { "type": "array", "items": { "type": "string" }, "default": [] }, "marketPressures": { "type": "array", "items": { "type": "string" }, "default": [] }, "buyingDynamics": { "type": "array", "items": { "type": "string" }, "default": [] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the segment", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the segment", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "unrecognized": { "type": "boolean" }, "rejected": { "type": "boolean" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "tagGroupOId": { "type": "string" }, "tagGroupName": { "type": "string" }, "tagOId": { "type": "string" }, "tagName": { "type": "string" } }, "required": [ "tagGroupOId", "tagGroupName", "tagOId", "tagName" ] } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName", "unrecognized", "rejected" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/segment/create": { "post": { "deprecated": false, "operationId": "createSegment", "summary": "Create Segment", "description": "Create a new market segment", "tags": [ "Segment" ], "x-visibility": "public", "requestBody": { "description": "Segment creation data", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The name of the segment", "example": "Enterprise Technology Companies" }, "description": { "type": "string", "description": "The description of the segment", "example": "Companies with 500+ employees in the technology sector" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this segment, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } }, "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating personas. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking this segment to offerings (products/services)" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Segment created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "strategicFit": { "type": "array", "items": { "type": "string" }, "default": [] }, "firmographics": { "type": "object", "properties": { "industry": { "type": "array", "items": { "type": "string" }, "default": [] }, "businessModel": { "type": "array", "items": { "type": "string" }, "default": [] }, "geography": { "type": "array", "items": { "type": "string" }, "default": [] }, "revenue": { "type": "array", "items": { "type": "string" }, "default": [] }, "employees": { "type": "array", "items": { "type": "string" }, "default": [] } }, "default": { "industry": [], "businessModel": [], "geography": [], "revenue": [], "employees": [] }, "additionalProperties": { "nullable": true } }, "operatingCharacteristics": { "type": "array", "items": { "type": "string" }, "default": [] }, "strategicPriorities": { "type": "array", "items": { "type": "string" }, "default": [] }, "marketPressures": { "type": "array", "items": { "type": "string" }, "default": [] }, "buyingDynamics": { "type": "array", "items": { "type": "string" }, "default": [] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the segment", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the segment", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "unrecognized": { "type": "boolean" }, "rejected": { "type": "boolean" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "tagGroupOId": { "type": "string" }, "tagGroupName": { "type": "string" }, "tagOId": { "type": "string" }, "tagName": { "type": "string" } }, "required": [ "tagGroupOId", "tagGroupName", "tagOId", "tagName" ] } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName", "unrecognized", "rejected" ] } }, "required": [ "_metadata", "data" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/segment/update": { "post": { "deprecated": false, "operationId": "updateSegment", "summary": "Update Segment", "description": "Update an existing market segment", "tags": [ "Segment" ], "x-visibility": "public", "requestBody": { "description": "Segment update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the segment to update", "example": "sg_1234" }, "name": { "type": "string", "description": "The name of the segment", "example": "Enterprise Technology Companies" }, "internalName": { "type": "string", "description": "The internal name of the segment", "example": "EnterpriseTech500Plus" }, "description": { "type": "string", "description": "A description of the segment", "example": "Large technology companies with 500+ employees seeking digital transformation" }, "strategicFit": { "type": "array", "items": { "type": "string" }, "description": "Why this segment matters to us: the fit between what we offer and what they need, and the unique attributes of this segment that align to our offering.", "example": [ "High contract values driven by complex operational requirements.", "Strong expansion potential as adoption spreads across departments." ] }, "operatingCharacteristics": { "type": "array", "items": { "type": "string" }, "description": "Internal, qualitative, often inferred traits that distinguish this segment: org structure, maturity, operating model, culture.", "example": [ "Cross-functional teams with shared ownership of outcomes spanning engineering and operations.", "Decision-making distributed across technical and business stakeholders." ] }, "buyingDynamics": { "type": "array", "items": { "type": "string" }, "description": "How this segment makes and acts on purchasing decisions: what drives evaluation, who's involved, how the process runs, and what signals a likely buyer.", "example": [ "Procurement and security review required before contract signature.", "Multi-stakeholder evaluation typically driven by an executive sponsor." ] }, "strategicPriorities": { "type": "array", "items": { "type": "string" }, "description": "Strategic priorities this segment is pursuing", "example": [ "Investing in automation to reduce manual operational overhead.", "Building data infrastructure to support real-time decision making." ] }, "marketPressures": { "type": "array", "items": { "type": "string" }, "description": "Market pressures affecting this segment", "example": [ "Increasing competition from well-funded startups offering point solutions.", "Regulatory complexity growing across multiple jurisdictions." ] }, "firmographics": { "type": "object", "properties": { "industry": { "type": "array", "items": { "type": "string" }, "default": [] }, "businessModel": { "type": "array", "items": { "type": "string" }, "default": [] }, "geography": { "type": "array", "items": { "type": "string" }, "default": [] }, "revenue": { "type": "array", "items": { "type": "string" }, "default": [] }, "employees": { "type": "array", "items": { "type": "string" }, "default": [] } }, "additionalProperties": { "nullable": true }, "description": "Structured firmographic data for the segment (industry, businessModel, geography, revenue, employees). Supports custom keys via passthrough." }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional segment information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this segment, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Segment updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "strategicFit": { "type": "array", "items": { "type": "string" }, "default": [] }, "firmographics": { "type": "object", "properties": { "industry": { "type": "array", "items": { "type": "string" }, "default": [] }, "businessModel": { "type": "array", "items": { "type": "string" }, "default": [] }, "geography": { "type": "array", "items": { "type": "string" }, "default": [] }, "revenue": { "type": "array", "items": { "type": "string" }, "default": [] }, "employees": { "type": "array", "items": { "type": "string" }, "default": [] } }, "default": { "industry": [], "businessModel": [], "geography": [], "revenue": [], "employees": [] }, "additionalProperties": { "nullable": true } }, "operatingCharacteristics": { "type": "array", "items": { "type": "string" }, "default": [] }, "strategicPriorities": { "type": "array", "items": { "type": "string" }, "default": [] }, "marketPressures": { "type": "array", "items": { "type": "string" }, "default": [] }, "buyingDynamics": { "type": "array", "items": { "type": "string" }, "default": [] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] } }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the segment", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the segment", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } }, "unrecognized": { "type": "boolean" }, "rejected": { "type": "boolean" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "tagGroupOId": { "type": "string" }, "tagGroupName": { "type": "string" }, "tagOId": { "type": "string" }, "tagName": { "type": "string" } }, "required": [ "tagGroupOId", "tagGroupName", "tagOId", "tagName" ] } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName", "unrecognized", "rejected" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Segment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/segment/delete": { "delete": { "deprecated": false, "operationId": "deleteSegment", "summary": "Delete Segment", "description": "Soft delete a Segment by OId. The segment will be marked as deleted but not permanently removed.", "tags": [ "Segment" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Segment OId" }, "required": true, "description": "Segment OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted segment data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Segment OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string", "description": "Segment name" }, "internalName": { "type": "string", "description": "Segment internal name" }, "description": { "type": "string", "nullable": true, "description": "Segment description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/SegmentData" }, "qualifyingQuestions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "question": { "type": "string", "description": "The question to ask to qualify the entity" }, "rationale": { "type": "string", "description": "The rationale for the question as to why it helps qualify" }, "fitType": { "type": "string", "enum": [ "GOOD", "BAD" ], "description": "The fit type of the question", "example": "GOOD" }, "weight": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "INSTANT_QUALIFIER", "INSTANT_DISQUALIFIER" ], "description": "The weight of the question", "example": "MEDIUM" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "The date and time the question was archived" } }, "required": [ "question", "rationale", "fitType", "weight" ] }, "description": "Qualifying questions" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the segment", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the segment", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" }, "unrecognized": { "type": "boolean" }, "rejected": { "type": "boolean" }, "intelOverride": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly" ] }, "guidance": { "type": "string", "nullable": true } } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "tagGroupOId": { "type": "string" }, "tagGroupName": { "type": "string" }, "tagOId": { "type": "string" }, "tagName": { "type": "string" } }, "required": [ "tagGroupOId", "tagGroupName", "tagOId", "tagName" ] } } }, "required": [ "_metadata", "oId", "createdAt", "name", "internalName", "unrecognized", "rejected" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Segment not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/proof-point/get": { "get": { "deprecated": false, "operationId": "getProofPoint", "summary": "Get Proof Point", "description": "Get Proof Point by OId", "tags": [ "Proof Point" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Proof Point OId" }, "required": true, "description": "Proof Point OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Proof Point data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Proof Point OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Proof Point name" }, "internalName": { "type": "string", "description": "Proof Point internal name" }, "description": { "type": "string", "nullable": true, "description": "Proof Point description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/ProofPointData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the proof point", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the proof point", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "updatedAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/proof-point/list": { "get": { "deprecated": false, "operationId": "listProofPoints", "summary": "List proof points", "description": "List proof points with optional filtering and pagination", "tags": [ "Proof Point" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by proof point OIds" }, "required": false, "description": "Filter by proof point OIds", "name": "oIds", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds." }, "required": false, "description": "Filter by offering OId. Accepts Product, Service, and Solution OIds.", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "deprecated": true }, "required": false, "description": "@deprecated Use `offeringOId` instead. Filter by offering OId (Product, Service, or Solution). Kept for backward compatibility.", "name": "productOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Text search query" }, "required": false, "description": "Text search query", "name": "textSearchQuery", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Proof Point list data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "example": false, "description": "Whether there are more results" }, "total": { "type": "number", "example": 0, "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProofPoint" }, "description": "Array of proof points" } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/proof-point/generate": { "post": { "deprecated": false, "operationId": "generateProofPoints", "summary": "Generate Proof Points", "description": "Generate proof points from source materials using AI. Each input array generates one proof point. Supports text, URLs, and generative names as sources.", "tags": [ "Proof Point" ], "x-visibility": "public", "requestBody": { "description": "Proof point generation input with source materials", "content": { "application/json": { "schema": { "type": "object", "properties": { "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when generating proof points. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking generated proof points to offerings (products/services)" } ] }, "proofPoints": { "$ref": "#/components/schemas/ProofPointGenerationInputs" }, "brandVoiceOId": { "type": "string", "description": "Brand voice oId to apply to generated proof points", "example": "bv_123456" } }, "required": [ "proofPoints" ] } } } }, "responses": { "200": { "description": "Proof points generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "theProof": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whatItSupports": { "type": "array", "nullable": true, "items": { "type": "string" } }, "howWeTalkAboutThis": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whyItMatters": { "type": "array", "nullable": true, "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "stat", "fact", "quote", "award", "recognition", "other" ] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the proof point", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the proof point", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - invalid sources or unable to process", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/proof-point/create": { "post": { "deprecated": false, "operationId": "createProofPoint", "summary": "Create Proof Point", "description": "Create a new proof point", "tags": [ "Proof Point" ], "x-visibility": "public", "requestBody": { "description": "Proof point creation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "The external name of the proof point", "example": "99% Customer Satisfaction" }, "internalName": { "type": "string", "description": "The internal name of the proof point", "example": "Customer Satisfaction Stat - Q4 2024" }, "description": { "type": "string", "description": "A description of the proof point", "example": "Our customer satisfaction rate consistently exceeds 99%" }, "type": { "type": "string", "enum": [ "stat", "fact", "quote", "award", "recognition", "other" ], "description": "The type of proof point", "example": "stat" }, "theProof": { "type": "array", "items": { "type": "string" }, "description": "The complete evidence statement: the actual fact, statistic, claim, metric, achievement or recognition AND where it comes from and when (if available).", "example": [ "99% customer satisfaction rate (annual NPS survey, 2024)." ] }, "whatItSupports": { "type": "array", "items": { "type": "string" }, "description": "The specific value claims, differentiators, or message this proof point backs up \u2014 what links the proof into the broader value story.", "example": [ "Backs the claim that our customer experience is best-in-class." ] }, "howWeTalkAboutThis": { "type": "array", "items": { "type": "string" }, "description": "Different ways to present or talk about this proof point", "example": [ "99% customer satisfaction rate", "Nearly perfect customer satisfaction", "Best-in-class customer experience" ] }, "whyItMatters": { "type": "array", "items": { "type": "string" }, "description": "The strategic frame for why this proof point is compelling: what objection it neutralizes, what doubt it removes, what conviction it builds.", "example": [ "Shows customer trust", "Demonstrates product quality", "Proves our commitment to excellence" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional proof point information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this proof point, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } }, "primaryOfferingOId": { "type": "string", "description": "Primary Offering to use as context when creating proof points. If not provided, the primary company attached to the Workspace will be used.", "example": "o_123456" }, "linkingStrategy": { "allOf": [ { "$ref": "#/components/schemas/LinkingStrategy" }, { "description": "Strategy for linking this proof point to offerings (products/services)" } ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Proof point created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "theProof": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whatItSupports": { "type": "array", "nullable": true, "items": { "type": "string" } }, "howWeTalkAboutThis": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whyItMatters": { "type": "array", "nullable": true, "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "stat", "fact", "quote", "award", "recognition", "other" ] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the proof point", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the proof point", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Offering not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/proof-point/update": { "post": { "deprecated": false, "operationId": "updateProofPoint", "summary": "Update Proof Point", "description": "Update an existing proof point", "tags": [ "Proof Point" ], "x-visibility": "public", "requestBody": { "description": "Proof point update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "minLength": 1, "description": "The ID of the proof point to update", "example": "pp_1234" }, "name": { "type": "string", "description": "The name of the proof point", "example": "50% Sales Improvement Case Study" }, "internalName": { "type": "string", "description": "The internal name of the proof point", "example": "CompanyX_Sales_Improvement_2024" }, "description": { "type": "string", "description": "A description of the proof point", "example": "Customer achieved 50% improvement in sales conversion rates within 6 months" }, "type": { "type": "string", "enum": [ "stat", "fact", "quote", "award", "recognition", "other" ], "description": "The type of proof point", "example": "stat" }, "theProof": { "type": "array", "items": { "type": "string" }, "description": "The complete evidence statement: the actual fact, statistic, claim, metric, achievement or recognition AND where it comes from and when (if available).", "example": [ "50% improvement in sales conversion rates over 6 months (Company X case study, 2024)." ] }, "whatItSupports": { "type": "array", "items": { "type": "string" }, "description": "The specific value claims, differentiators, or message this proof point backs up \u2014 what links the proof into the broader value story.", "example": [ "Backs the claim that our solution drives near-term, quantifiable revenue impact." ] }, "howWeTalkAboutThis": { "type": "array", "items": { "type": "string" }, "description": "How we talk about this proof point", "example": [ "Our solution helped Company X achieve a 50% improvement in sales conversion rates", "Within 6 months, Company X saw significant improvement in their sales process efficiency" ] }, "whyItMatters": { "type": "array", "items": { "type": "string" }, "description": "The strategic frame for why this proof point is compelling: what objection it neutralizes, what doubt it removes, what conviction it builds.", "example": [ "Demonstrates quantifiable ROI in a short timeframe", "Shows real-world impact on sales performance", "Validates our solution's effectiveness in the enterprise market" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional proof point information" } ] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] }, "description": "Workspace-defined additional property values for this proof point, keyed by property key.", "example": { "tier": "Enterprise", "region": "APAC" } } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Proof point updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "name": { "type": "string" }, "internalName": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "default": true }, "data": { "type": "object", "nullable": true, "properties": { "theProof": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whatItSupports": { "type": "array", "nullable": true, "items": { "type": "string" } }, "howWeTalkAboutThis": { "type": "array", "nullable": true, "items": { "type": "string" } }, "whyItMatters": { "type": "array", "nullable": true, "items": { "type": "string" } }, "type": { "type": "string", "enum": [ "stat", "fact", "quote", "award", "recognition", "other" ] }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } } } }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the proof point", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the proof point", "example": "Doe" } } }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } } } }, "required": [ "oId", "createdAt", "updatedAt", "name", "internalName" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Proof point not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/proof-point/delete": { "delete": { "deprecated": false, "operationId": "deleteProofPoint", "summary": "Delete Proof Point", "description": "Soft delete a Proof Point by OId. The proof point will be marked as deleted but not permanently removed.", "tags": [ "Proof Point" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Proof Point OId" }, "required": true, "description": "Proof Point OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deleted proof point data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Proof Point OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Archived date" }, "name": { "type": "string", "description": "Proof Point name" }, "internalName": { "type": "string", "description": "Proof Point internal name" }, "description": { "type": "string", "nullable": true, "description": "Proof Point description" }, "active": { "type": "boolean", "default": true }, "data": { "$ref": "#/components/schemas/ProofPointData" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true, "description": "The first name of the user who created the proof point", "example": "John" }, "lastName": { "type": "string", "nullable": true, "description": "The last name of the user who created the proof point", "example": "Doe" } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "updatedAt", "name", "internalName" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Proof Point not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/agents/context/run": { "post": { "deprecated": false, "operationId": "runContextAgent", "summary": "Context Agent Run", "description": "Run a preset context agent by agentOId. The agent's configuration (topK, rerank, sources, etc.) is loaded from the database. Runtime input only provides query and optional additionalContext.", "tags": [ "Agents", "Context" ], "x-visibility": "public", "requestBody": { "description": "Context agent input (query + context)", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Question or task to fetch context for" }, "additionalContext": { "type": "object", "nullable": true, "properties": { "person": { "type": "object", "nullable": true, "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "format": "email" }, "linkedInProfileUrl": { "type": "string", "nullable": true, "format": "uri" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true } }, "description": "Optional context about the person associated with the query" }, "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "linkedInProfileUrl": { "type": "string", "nullable": true, "format": "uri" }, "crmAccountId": { "type": "string", "nullable": true } }, "description": "Optional context about the company associated with the query" }, "details": { "type": "string", "nullable": true, "description": "Free-form text providing additional context" } }, "description": "Optional person/company/details to enhance search" }, "agentOId": { "type": "string", "description": "Agent OId for preset context configuration", "example": "agent_abc123" }, "runtimeContext": { "type": "string", "minLength": 1, "description": "Runtime context string \u2014 used as the query if 'query' is not provided. Consistent with other agent type APIs (email, content, enrich, etc.)." } }, "required": [ "agentOId" ], "description": "Context agent input with query and optional context", "example": { "agentOId": "agent_abc123", "runtimeContext": "How do you help with HIPAA compliance?", "additionalContext": { "person": { "firstName": "John", "lastName": "Doe", "title": "CISO", "email": "john.doe@healthcare.com" }, "company": { "name": "Healthcare Corp", "domain": "healthcare.com" }, "details": "Large healthcare provider in California" } } } } } }, "responses": { "200": { "description": "Context agent run successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether the operation was successful", "example": true }, "message": { "type": "string", "nullable": true, "description": "Message", "example": "Additional information" }, "data": { "$ref": "#/components/schemas/ContextAgentData" } }, "required": [ "_metadata", "found", "data" ] } } } }, "400": { "description": "Bad request - invalid input or agent type mismatch", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Agent not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/context": { "post": { "deprecated": false, "operationId": "searchContext", "summary": "Context Search", "description": "Search for relevant context documents from library entities, resources, and external research. Supports inline configuration for query enhancement, reranking, and reasoning generation.", "tags": [ "Context" ], "x-visibility": "public", "requestBody": { "description": "Context search input with configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Question or task to fetch context for" }, "additionalContext": { "type": "object", "nullable": true, "properties": { "person": { "type": "object", "nullable": true, "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true, "format": "email" }, "linkedInProfileUrl": { "type": "string", "nullable": true, "format": "uri" }, "crmContactId": { "type": "string", "nullable": true }, "crmLeadId": { "type": "string", "nullable": true }, "crmAccountId": { "type": "string", "nullable": true } }, "description": "Optional context about the person associated with the query" }, "company": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true }, "domain": { "type": "string", "nullable": true }, "linkedInProfileUrl": { "type": "string", "nullable": true, "format": "uri" }, "crmAccountId": { "type": "string", "nullable": true } }, "description": "Optional context about the company associated with the query" }, "details": { "type": "string", "nullable": true, "description": "Free-form text providing additional context" } }, "description": "Optional person/company/details to enhance search" }, "topK": { "type": "number" }, "rerank": { "type": "string", "enum": [ "off", "low", "medium", "high", "best" ] }, "sources": { "type": "object", "properties": { "library": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "resources": { "type": "object", "properties": { "enabled": { "type": "boolean" } } } } }, "tools": { "type": "object", "properties": { "personProfile": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "returnOutput": { "type": "boolean", "description": "Include profile in output documents" }, "guess": { "type": "boolean", "description": "Attempt to guess LinkedIn profile if not provided" } } }, "companyProfile": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "returnOutput": { "type": "boolean", "description": "Include profile in output documents" } } }, "companyResearch": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "returnOutput": { "type": "boolean", "description": "Include research in output documents" } } }, "personResearch": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "returnOutput": { "type": "boolean", "description": "Include research in output documents" } } }, "deepWebResearch": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false }, "returnOutput": { "type": "boolean", "description": "Include web results in output documents" } } } } }, "agentTools": { "type": "object", "properties": { "brandVoice": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "brandVoiceOId": { "type": "string" } } }, "webSearch": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "allowedDomains": { "type": "array", "items": { "type": "string" } } } }, "parallelWebSearch": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "allowedDomains": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "auto", "advanced" ] }, "customInstructions": { "type": "string" } } }, "highEffortMode": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "crmActivity": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "mode": { "type": "string", "enum": [ "auto", "advanced", "analyze", "read" ] }, "activityTypes": { "type": "array", "items": { "type": "string", "enum": [ "notes", "tasks", "calls", "emails" ] } }, "guessEmailFromLinkedIn": { "type": "boolean" }, "leadConfig": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxActivities": { "type": "number", "minimum": 0, "maximum": 50 }, "activityLookbackDays": { "type": "number", "minimum": 1, "maximum": 365 }, "fields": { "type": "array", "items": { "type": "string" } }, "additionalFields": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string", "minLength": 1, "description": "CRM API field name to fetch (e.g., 'Competitor__c', 'Industry', 'hs_lead_status'). Use the get_crm_entity_schema tool first to discover the exact API names for an entity \u2014 a wrong name returns nothing, which is indistinguishable from an empty field." }, "description": { "type": "string" } } } } } }, "contactConfig": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxActivities": { "type": "number", "minimum": 0, "maximum": 50 }, "activityLookbackDays": { "type": "number", "minimum": 1, "maximum": 365 }, "fields": { "type": "array", "items": { "type": "string" } }, "additionalFields": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string", "minLength": 1, "description": "CRM API field name to fetch (e.g., 'Competitor__c', 'Industry', 'hs_lead_status'). Use the get_crm_entity_schema tool first to discover the exact API names for an entity \u2014 a wrong name returns nothing, which is indistinguishable from an empty field." }, "description": { "type": "string" } } } } } }, "accountConfig": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxActivities": { "type": "number", "minimum": 0, "maximum": 50 }, "activityLookbackDays": { "type": "number", "minimum": 1, "maximum": 365 }, "fields": { "type": "array", "items": { "type": "string" } }, "additionalFields": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string", "minLength": 1, "description": "CRM API field name to fetch (e.g., 'Competitor__c', 'Industry', 'hs_lead_status'). Use the get_crm_entity_schema tool first to discover the exact API names for an entity \u2014 a wrong name returns nothing, which is indistinguishable from an empty field." }, "description": { "type": "string" } } } } } }, "opportunityConfig": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "maxActivities": { "type": "number", "minimum": 0, "maximum": 50 }, "activityLookbackDays": { "type": "number", "minimum": 1, "maximum": 365 }, "fields": { "type": "array", "items": { "type": "string" } }, "additionalFields": { "type": "array", "items": { "type": "object", "properties": { "fieldName": { "type": "string", "minLength": 1, "description": "CRM API field name to fetch (e.g., 'Competitor__c', 'Industry', 'hs_lead_status'). Use the get_crm_entity_schema tool first to discover the exact API names for an entity \u2014 a wrong name returns nothing, which is indistinguishable from an empty field." }, "description": { "type": "string" } } } } } }, "customInstructions": { "type": "string" } } }, "customTask": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "prompt": { "type": "string" }, "jsonSchema": { "type": "string" } } }, "personResearch": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "companyResearch": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "graphContext": { "type": "object", "properties": { "enabled": { "type": "boolean" } } } } }, "reasoning": { "type": "object", "properties": { "perDocument": { "type": "boolean", "description": "Generate reasoning explanation for each document" }, "overall": { "type": "boolean", "description": "Generate overall summary of how documents collectively help" } } }, "commonContext": { "type": "object", "nullable": true, "properties": { "accountBasedMode": { "type": "boolean" }, "entities": { "type": "object", "properties": { "product": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "bestMatchFallbackMode": { "type": "string", "enum": [ "DONT_USE", "FORCE_USE", "EXIT_EARLY", "FALLBACK_TO_OID" ] }, "fallbackOIds": { "type": "array", "nullable": true, "items": { "type": "string" } } } }, "service": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "bestMatchFallbackMode": { "type": "string", "enum": [ "DONT_USE", "FORCE_USE", "EXIT_EARLY", "FALLBACK_TO_OID" ] }, "fallbackOIds": { "type": "array", "nullable": true, "items": { "type": "string" } } } }, "solution": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "bestMatchFallbackMode": { "type": "string", "enum": [ "DONT_USE", "FORCE_USE", "EXIT_EARLY", "FALLBACK_TO_OID" ] }, "fallbackOIds": { "type": "array", "nullable": true, "items": { "type": "string" } } } }, "playbook": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "bestMatchFallbackMode": { "type": "string", "enum": [ "DONT_USE", "FORCE_USE", "EXIT_EARLY", "FALLBACK_TO_OID" ] }, "bestMatchAllowedPlaybookTypes": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "LEGACY", "SECTOR", "SOLUTION", "MILESTONE", "PRACTITIONER", "COMPETITIVE", "ACCOUNT", "CUSTOM" ] } }, "fallbackOIds": { "type": "array", "nullable": true, "items": { "type": "string" } } } }, "persona": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "useCase": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "referenceCustomer": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "segment": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "competitor": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "alternative": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "buyingTrigger": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "objection": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "proofPoint": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "coreFeature": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "motion": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } }, "motionPlaybook": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "bestMatchFallbackMode": { "type": "string", "enum": [ "DONT_USE", "FORCE_USE", "EXIT_EARLY", "FALLBACK_TO_OID" ] }, "motionType": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ] } } }, "skill": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "BEST_MATCH", "MANUAL", "NONE" ] }, "oIds": { "type": "array", "items": { "type": "string" } }, "numItems": { "type": "number" }, "bestMatchMinConfidenceLevel": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] } } } } }, "includeRuntimeValueProps": { "type": "boolean" }, "context": { "type": "string", "nullable": true }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "GOOGLE_DRIVE_FILE_ID", "GENERATIVE_NAME", "OID", "COMPANY_NAME", "FIELDWISE_DOCUMENT_ID", "RAG_DOCUMENT_ID", "RESOURCE", "REPORT", "REPORT_SECTION", "EVENT_OID_FINDINGS", "FINDING_OIDS" ] }, "value": { "type": "string" }, "name": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "useNameIfUrlFails": { "type": "boolean", "nullable": true } } } }, "page": { "type": "object", "properties": { "url": { "type": "string" }, "pageType": { "type": "string", "enum": [ "PERSONA_DETAIL", "PRODUCT_DETAIL", "SERVICE_DETAIL", "SOLUTION_DETAIL", "PLAYBOOK_DETAIL", "USE_CASE_DETAIL", "SEGMENT_DETAIL", "COMPETITOR_DETAIL", "REFERENCE_DETAIL", "PROOF_POINT_DETAIL", "EVENT_DETAIL", "MOTION_ICP_DETAIL", "SKILL_DETAIL", "ASK_OCTAVE", "OTHER" ] }, "targetEntityOId": { "type": "string" }, "targetEntityName": { "type": "string" }, "targetEntityType": { "type": "string" }, "additionalContext": { "type": "string" } } }, "mergeManualContext": { "type": "boolean" } } } }, "required": [ "query" ], "description": "Context search input with inline configuration", "example": { "query": "How do you help with HIPAA compliance?", "additionalContext": { "person": { "firstName": "John", "lastName": "Doe", "title": "CISO", "email": "john.doe@healthcare.com" }, "company": { "name": "Healthcare Corp", "domain": "healthcare.com" }, "details": "Large healthcare provider in California" }, "topK": 10, "rerank": "medium", "sources": { "library": { "enabled": true }, "resources": { "enabled": true } }, "tools": { "personProfile": { "enabled": false, "returnOutput": true, "guess": false }, "companyProfile": { "enabled": false, "returnOutput": true }, "companyResearch": { "enabled": false, "returnOutput": true }, "personResearch": { "enabled": false, "returnOutput": true }, "deepWebResearch": { "enabled": false, "returnOutput": true } }, "agentTools": { "crmActivity": { "enabled": false }, "graphContext": { "enabled": false } }, "reasoning": { "perDocument": false, "overall": false } } } } } }, "responses": { "200": { "description": "Context search successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/ContextData" }, "usage": { "type": "number", "description": "Usage count for billing/credits" }, "found": { "type": "boolean", "description": "Whether the query was found" }, "message": { "type": "string", "description": "Message from the context agent" } }, "required": [ "_metadata", "data", "usage", "found", "message" ] } } } }, "400": { "description": "Bad request - invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/brand-voice/create": { "post": { "deprecated": false, "operationId": "createBrandVoice", "summary": "Create Brand Voice", "description": "Create a new brand voice from explicit/literal data (use generate endpoint for AI-powered creation from sources)", "tags": [ "Brand Voice" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "description": "The name/title of the brand voice", "example": "Enterprise Brand Voice" }, "description": { "type": "string", "description": "High-level description of this brand voice", "example": "Professional and authoritative tone for enterprise audiences" }, "essence": { "type": "string", "nullable": true, "description": "The core essence or soul of the brand voice", "example": "Clear, concise, and confident" }, "personality": { "type": "object", "properties": { "coreTraits": { "type": "array", "items": { "type": "string" }, "description": "Core personality traits that define the brand voice", "example": [ "Professional", "Authoritative", "Empathetic" ] }, "guidingPrinciples": { "type": "array", "items": { "type": "string" }, "description": "Guiding principles for communication style", "example": [ "Clarity over cleverness", "Lead with value" ] } }, "required": [ "coreTraits", "guidingPrinciples" ], "description": "Brand personality definition" }, "tonality": { "type": "object", "properties": { "soundLike": { "type": "array", "items": { "type": "string" }, "description": "Desired tonal qualities the brand should embody", "example": [ "Confident expert", "Trusted advisor" ] }, "neverSoundLike": { "type": "array", "items": { "type": "string" }, "description": "Tonal qualities the brand should avoid", "example": [ "Pushy salesperson", "Corporate jargon" ] } }, "required": [ "soundLike", "neverSoundLike" ], "description": "Brand tonality guidelines" }, "vocabulary": { "type": "object", "properties": { "keyCompanyTerms": { "type": "array", "items": { "type": "string" }, "description": "Preferred company-specific terminology", "example": [ "Octave", "knowledge graph", "GTM intelligence" ] }, "keySubstitutions": { "type": "array", "items": { "type": "string" }, "description": "Word or phrase substitutions to enforce", "example": [ "Say 'revenue team' not 'sales team'" ] } }, "required": [ "keyCompanyTerms", "keySubstitutions" ], "description": "Vocabulary preferences and terminology" }, "writingRules": { "type": "object", "properties": { "languageRules": { "type": "array", "items": { "type": "string" }, "description": "Grammatical and language rules to follow", "example": [ "Use active voice", "Avoid passive constructions" ] }, "formattingFundamentals": { "type": "array", "items": { "type": "string" }, "description": "Formatting guidelines for content structure", "example": [ "Short paragraphs", "Bullet points for lists" ] } }, "required": [ "languageRules", "formattingFundamentals" ], "description": "Writing style and formatting rules" }, "audienceConsiderations": { "type": "object", "properties": { "qualitiesAndCharacteristics": { "type": "array", "items": { "type": "string" }, "description": "Key qualities and characteristics of the target audience", "example": [ "Technical decision makers", "Data-driven professionals" ] }, "aspirationsAndBoundaries": { "type": "array", "items": { "type": "string" }, "description": "Audience aspirations to address and communication boundaries to respect", "example": [ "Want actionable insights", "No fluff or filler" ] } }, "required": [ "qualitiesAndCharacteristics", "aspirationsAndBoundaries" ], "description": "Target audience considerations" } }, "required": [ "title", "description", "personality", "tonality", "vocabulary", "writingRules", "audienceConsiderations" ] } } } }, "responses": { "200": { "description": "Created brand voice", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/BrandVoice" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/brand-voice/get": { "get": { "deprecated": false, "operationId": "getBrandVoice", "summary": "Get Brand Voice", "description": "Get Brand Voice by OId", "tags": [ "Brand Voice" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Brand Voice OId" }, "required": true, "description": "Brand Voice OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Brand Voice data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "oId": { "type": "string", "description": "Brand Voice OId" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Creation date" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Updated date" }, "deletedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Deleted date" }, "name": { "type": "string", "description": "Brand Voice name" }, "data": { "$ref": "#/components/schemas/BrandVoiceData" }, "default": { "type": "boolean", "default": false, "description": "Whether this is the default brand voice for the workspace" }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "description": "User data" }, "workspace": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string", "nullable": true } }, "description": "Workspace data" } }, "required": [ "_metadata", "oId", "createdAt", "updatedAt", "name" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/brand-voice/list": { "get": { "deprecated": false, "operationId": "listBrandVoices", "summary": "List Brand Voices", "description": "List all brand voices in the workspace", "tags": [ "Brand Voice" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "number", "nullable": true, "default": 10, "description": "Maximum number of results to return" }, "required": false, "description": "Maximum number of results to return", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Number of results to skip" }, "required": false, "description": "Number of results to skip", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of brand voices", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/BrandVoiceList" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/brand-voice/update": { "post": { "deprecated": false, "operationId": "updateBrandVoice", "summary": "Update Brand Voice", "description": "Update an existing brand voice", "tags": [ "Brand Voice" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "Brand Voice OId" }, "name": { "type": "string", "description": "Brand Voice name" }, "data": { "type": "object", "properties": { "title": { "type": "string", "description": "The name/title of the brand voice", "example": "Enterprise Brand Voice" }, "description": { "type": "string", "description": "High-level description of this brand voice", "example": "Professional and authoritative tone for enterprise audiences" }, "essence": { "type": "string", "nullable": true, "description": "The core essence or soul of the brand voice", "example": "Clear, concise, and confident" }, "personality": { "type": "object", "properties": { "coreTraits": { "type": "array", "items": { "type": "string" }, "description": "Core personality traits that define the brand voice", "example": [ "Professional", "Authoritative", "Empathetic" ] }, "guidingPrinciples": { "type": "array", "items": { "type": "string" }, "description": "Guiding principles for communication style", "example": [ "Clarity over cleverness", "Lead with value" ] } }, "required": [ "coreTraits", "guidingPrinciples" ], "description": "Brand personality definition" }, "tonality": { "type": "object", "properties": { "soundLike": { "type": "array", "items": { "type": "string" }, "description": "Desired tonal qualities the brand should embody", "example": [ "Confident expert", "Trusted advisor" ] }, "neverSoundLike": { "type": "array", "items": { "type": "string" }, "description": "Tonal qualities the brand should avoid", "example": [ "Pushy salesperson", "Corporate jargon" ] } }, "required": [ "soundLike", "neverSoundLike" ], "description": "Brand tonality guidelines" }, "vocabulary": { "type": "object", "properties": { "keyCompanyTerms": { "type": "array", "items": { "type": "string" }, "description": "Preferred company-specific terminology", "example": [ "Octave", "knowledge graph", "GTM intelligence" ] }, "keySubstitutions": { "type": "array", "items": { "type": "string" }, "description": "Word or phrase substitutions to enforce", "example": [ "Say 'revenue team' not 'sales team'" ] } }, "required": [ "keyCompanyTerms", "keySubstitutions" ], "description": "Vocabulary preferences and terminology" }, "writingRules": { "type": "object", "properties": { "languageRules": { "type": "array", "items": { "type": "string" }, "description": "Grammatical and language rules to follow", "example": [ "Use active voice", "Avoid passive constructions" ] }, "formattingFundamentals": { "type": "array", "items": { "type": "string" }, "description": "Formatting guidelines for content structure", "example": [ "Short paragraphs", "Bullet points for lists" ] } }, "required": [ "languageRules", "formattingFundamentals" ], "description": "Writing style and formatting rules" }, "audienceConsiderations": { "type": "object", "properties": { "qualitiesAndCharacteristics": { "type": "array", "items": { "type": "string" }, "description": "Key qualities and characteristics of the target audience", "example": [ "Technical decision makers", "Data-driven professionals" ] }, "aspirationsAndBoundaries": { "type": "array", "items": { "type": "string" }, "description": "Audience aspirations to address and communication boundaries to respect", "example": [ "Want actionable insights", "No fluff or filler" ] } }, "required": [ "qualitiesAndCharacteristics", "aspirationsAndBoundaries" ], "description": "Target audience considerations" }, "customFields": { "$ref": "#/components/schemas/CustomDataFields" } }, "required": [ "title", "description", "personality", "tonality", "vocabulary", "writingRules", "audienceConsiderations" ], "description": "Brand Voice data" } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Updated brand voice", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/BrandVoice" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/brand-voice/generate": { "post": { "deprecated": false, "operationId": "generateBrandVoice", "summary": "Generate Brand Voice", "description": "Generate and create brand voice from sources using AI", "tags": [ "Brand Voice" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the brand voice" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to analyze for brand voice generation" } }, "required": [ "name", "sources" ] } } } }, "responses": { "200": { "description": "Created brand voice", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/BrandVoice" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/brand-voice/toggle-default": { "post": { "deprecated": false, "operationId": "toggleDefaultBrandVoice", "summary": "Toggle Default Brand Voice", "description": "Toggle a brand voice as the workspace default. If already default, it will be unset. If not default, it will be set as default (unsetting any existing default).", "tags": [ "Brand Voice" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "Brand Voice OId to toggle as default" } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Updated brand voice (default status toggled)", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/BrandVoice" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/brand-voice/apply": { "post": { "deprecated": false, "operationId": "applyBrandVoice", "summary": "Apply Brand Voice", "description": "Apply brand voice transformation to sources. Uses default brand voice if none specified. Credits: NOTE=5, PULSE=10, ECHO=20, HARMONY=30 per source.", "tags": [ "Brand Voice" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Source materials to apply brand voice to" }, "brandVoiceOId": { "type": "string", "description": "Brand Voice OId to apply. If not provided, uses workspace default." }, "modelType": { "anyOf": [ { "type": "string", "enum": [ "NOTE", "PULSE", "ECHO", "HARMONY", "CHORUS", "SYMPHONY" ] }, { "type": "string", "enum": [ "SPEED" ] }, { "type": "string", "enum": [ "BALANCED" ] }, { "type": "string", "enum": [ "DETAILED" ] } ], "default": "ECHO", "description": "Model quality tier. NOTE=5 credits, PULSE=10 credits, ECHO=20 credits, HARMONY=30 credits per source", "example": "ECHO" }, "includeOriginal": { "type": "boolean", "default": false, "description": "Include the original expanded content in the response. Defaults to false.", "example": false } }, "required": [ "sources" ] } } } }, "responses": { "200": { "description": "Transformed sources with brand voice applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "originalSource": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" } }, "required": [ "type", "value" ] }, "originalContent": { "type": "string", "description": "Original expanded content (only included if includeOriginal=true)" }, "reasoning": { "type": "string", "description": "Explanation of transformation choices and brand voice elements applied" }, "transformedContent": { "type": "string", "description": "Content with brand voice applied" } }, "required": [ "originalSource", "reasoning", "transformedContent" ] } } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/resource/get": { "get": { "deprecated": false, "operationId": "getResource", "summary": "Get Resource", "description": "Get a resource by OId. Returns the full extracted text content by default (set includeContent=false to skip and only fetch metadata). Optionally check storage task status for pending/uploading resources.", "tags": [ "Resource" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Resource OId", "example": "res_abc123" }, "required": true, "description": "Resource OId", "name": "oId", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": false, "description": "Whether to check and return the current Fieldwise storage task status", "example": true }, "required": false, "description": "Whether to check and return the current Fieldwise storage task status", "name": "checkStorageTaskStatus", "in": "query" }, { "schema": { "type": "boolean", "nullable": true, "default": true, "description": "Whether to include the full extracted text content of the resource as a single string. Only works for indexed resources. Set to false when polling for upload status to avoid fetching content on every poll.", "example": true }, "required": false, "description": "Whether to include the full extracted text content of the resource as a single string. Only works for indexed resources. Set to false when polling for upload status to avoid fetching content on every poll.", "name": "includeContent", "in": "query" } ], "responses": { "200": { "description": "Resource data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "google_drive", "notion", "linear", "text", "octave_asset" ] }, "name": { "type": "string", "nullable": true }, "identifier": { "type": "string" }, "sourceUrl": { "type": "string", "description": "External deep link to view the source item, across all source types: the provider URL for Drive/Notion/Linear resources, the page URL for website (url) resources. Absent for sources with no external surface (text, file uploads)." }, "metadata": { "anyOf": [ { "allOf": [ { "type": "object", "properties": { "ragTaskIdentifier": { "type": "string" }, "taskStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "externalFilePath": { "type": "string", "description": "File path in fieldwise, use this to download the file from fieldwise" }, "title": { "type": "string" }, "description": { "type": "string" }, "faviconUrl": { "type": "string" }, "logoUrl": { "type": "string" }, "statusCode": { "type": "number" }, "isWorkspacePrimarySource": { "type": "boolean", "description": "Whether the resource is the primary source for the workspace" }, "isMainResource": { "type": "boolean", "description": "Entry point of resource tree" }, "asyncCrawlComplete": { "type": "boolean", "description": "Whether async crawl for child pages has completed (for main website resources)" }, "crawlQueuedAt": { "type": "string", "description": "ISO timestamp of when the most recent async child-page crawl was queued. Lets the UI distinguish an in-flight crawl (recent) from a stuck one (old) while asyncCrawlComplete is false." }, "originalFileName": { "type": "string", "description": "Original file name for file uploads" }, "sourceItemType": { "type": "string", "enum": [ "file", "folder" ], "description": "Whether the source item is a leaf (file / page) or a container (folder / database)" }, "sourceItemUrl": { "type": "string", "description": "Public/external URL to view the source item" }, "sourceLastModifiedTime": { "type": "string", "description": "Last-modified timestamp reported by the source provider" }, "isContainer": { "type": "boolean", "description": "Whether this resource is a container (Notion database / Drive folder) that wraps child resources" }, "lastSyncedAt": { "type": "string", "description": "ISO timestamp of the last successful container membership sync" }, "containerSyncOverflowed": { "type": "boolean", "description": "True when the most recent sync stopped creating new children because the workspace resource limit was reached" }, "containerSyncTruncated": { "type": "boolean", "description": "True when the most recent sync listed only a prefix of the source database because it exceeded the per-sync page cap (MAX_PAGES_PER_DATABASE_SYNC). Pages beyond the cap are not indexed and child pruning is skipped for that pass." }, "ignoredChildCount": { "type": "integer", "description": "Container resources: number of source items skipped on the most recent sync because they're nested containers (sub-folders / sub-databases). v1 indexes only top-level items." }, "firstFailedAccessAt": { "type": "string", "description": "ISO timestamp of the first time the source became inaccessible (container 404 / trashed). Stamped on the first FAILED transition and cleared on a successful re-list. Used by the terminal stale-resource prune to measure how long the source has been failing by wall-clock time, since updatedAt is bumped on every re-list." }, "artifactUuid": { "type": "string", "description": "Octave asset resources: the artifact uuid in the octave-artifacts store (container and children)" }, "artifactFilePath": { "type": "string", "description": "Octave asset child resources: path of the indexed file within the artifact (e.g. 'index.html')" }, "artifactVersion": { "type": "integer", "description": "Octave asset container resources: the artifact currentVersion the children were last reconciled against \u2014 the cheap 'anything changed?' gate before per-file hashing" } } }, { "type": "object", "additionalProperties": { "nullable": true } } ] }, { "nullable": true } ] }, "settings": { "anyOf": [ { "allOf": [ { "type": "object", "properties": { "excludeFromReIndexing": { "type": "boolean", "description": "Whether the resource is excluded from re-indexing, can be used for entitlement limits" } } }, { "type": "object", "additionalProperties": { "nullable": true } } ] }, { "nullable": true } ] }, "encodedData": { "type": "string", "nullable": true }, "ragDocumentId": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "pending", "uploading", "indexed", "failed", null ] }, "workspaceOId": { "type": "string" }, "isParentResource": { "type": "boolean" }, "isGlobal": { "type": "boolean" }, "lastIndexedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "hasChildren": { "type": "boolean", "description": "Whether the resource has children, if true use oId to list children resources" }, "totalChildren": { "type": "number", "description": "Total number of children resources" }, "linearChildTypeCounts": { "type": "object", "properties": { "document": { "type": "number" }, "update": { "type": "number" }, "issue": { "type": "number" } }, "required": [ "document", "update", "issue" ], "description": "For Linear containers: child counts grouped by leaf kind (documents / project updates / issues). Legacy issue rows with no leaf kind count as issues." }, "isContainer": { "type": "boolean", "description": "True when this resource is a Notion database / Drive folder wrapper; children are listed via parentResourceOId" }, "lastSyncedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Container resources: timestamp of the last successful membership sync" }, "containerSyncOverflowed": { "type": "boolean", "description": "Container resources: true when sync skipped new children due to workspace resource limit" }, "containerSyncTruncated": { "type": "boolean", "description": "Container resources: true when the source database exceeded the per-sync page cap, so only a prefix was listed/indexed and pruning was skipped" }, "ignoredChildCount": { "type": "integer", "description": "Container resources: number of nested sub-folders / sub-databases skipped on the most recent sync (v1 indexes only top-level items)" }, "parentResourceOId": { "type": "string", "description": "Child resources: oId of the container (Notion database / Drive folder) this resource belongs to. Absent for standalone resources." }, "parentResourceName": { "type": "string", "description": "Child resources: display name of the container, suitable for UI surfacing without an extra fetch." }, "firstFailedAccessAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Container resources: timestamp of the first time the source became inaccessible. Present while the container is FAILED; absent once it recovers." }, "staleContainerPruneEta": { "type": "string", "nullable": true, "format": "date-time", "description": "FAILED container resources: projected date when the container and its children will be terminally pruned (firstFailedAccessAt + the prune window). Drives the 'will be removed in N days' UI warning. Absent for healthy containers." }, "storageData": { "type": "object", "properties": { "taskStatus": { "type": "string", "nullable": true, "enum": [ "pending", "processing", "completed", "failed", null ] }, "ragTaskIdentifier": { "type": "string", "nullable": true }, "filePath": { "type": "string", "nullable": true }, "ragDocumentId": { "type": "string", "nullable": true } } }, "uploadedByUserOId": { "type": "string", "nullable": true }, "content": { "type": "string", "nullable": true, "description": "Full extracted text content of the indexed resource as a single string. Present when includeContent=true. Null when the resource has not yet been indexed." } }, "required": [ "oId", "sourceType", "identifier", "workspaceOId", "isParentResource", "isGlobal", "createdAt", "updatedAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/resource/list": { "get": { "deprecated": false, "operationId": "listResources", "summary": "List Resources", "description": "List all global resources in the workspace with optional filtering and pagination. Only returns global resources (workspace-wide), not entity-specific resources.", "tags": [ "Resource" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "number", "nullable": true, "default": 20, "description": "Maximum number of resources to return (default: 20)", "example": 20 }, "required": false, "description": "Maximum number of resources to return (default: 20)", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "default": 0, "description": "Pagination offset (default: 0)", "example": 0 }, "required": false, "description": "Pagination offset (default: 0)", "name": "offset", "in": "query" }, { "schema": { "type": "string", "enum": [ "url", "google_drive", "notion", "linear", "text", "octave_asset" ], "description": "Filter by resource type: URL, GOOGLE_DRIVE, or TEXT" }, "required": false, "description": "Filter by resource type: URL, GOOGLE_DRIVE, or TEXT", "name": "resourceType", "in": "query" }, { "schema": { "type": "string", "description": "Search resources by name (case-insensitive)", "example": "landing page" }, "required": false, "description": "Search resources by name (case-insensitive)", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "uploading", "indexed", "failed" ], "description": "Filter by resource status: PENDING, UPLOADING, INDEXED, or FAILED" }, "required": false, "description": "Filter by resource status: PENDING, UPLOADING, INDEXED, or FAILED", "name": "status", "in": "query" } ], "responses": { "200": { "description": "List of resources", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "google_drive", "notion", "linear", "text", "octave_asset" ] }, "name": { "type": "string", "nullable": true }, "identifier": { "type": "string" }, "sourceUrl": { "type": "string", "description": "External deep link to view the source item, across all source types: the provider URL for Drive/Notion/Linear resources, the page URL for website (url) resources. Absent for sources with no external surface (text, file uploads)." }, "metadata": { "anyOf": [ { "allOf": [ { "type": "object", "properties": { "ragTaskIdentifier": { "type": "string" }, "taskStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "externalFilePath": { "type": "string", "description": "File path in fieldwise, use this to download the file from fieldwise" }, "title": { "type": "string" }, "description": { "type": "string" }, "faviconUrl": { "type": "string" }, "logoUrl": { "type": "string" }, "statusCode": { "type": "number" }, "isWorkspacePrimarySource": { "type": "boolean", "description": "Whether the resource is the primary source for the workspace" }, "isMainResource": { "type": "boolean", "description": "Entry point of resource tree" }, "asyncCrawlComplete": { "type": "boolean", "description": "Whether async crawl for child pages has completed (for main website resources)" }, "crawlQueuedAt": { "type": "string", "description": "ISO timestamp of when the most recent async child-page crawl was queued. Lets the UI distinguish an in-flight crawl (recent) from a stuck one (old) while asyncCrawlComplete is false." }, "originalFileName": { "type": "string", "description": "Original file name for file uploads" }, "sourceItemType": { "type": "string", "enum": [ "file", "folder" ], "description": "Whether the source item is a leaf (file / page) or a container (folder / database)" }, "sourceItemUrl": { "type": "string", "description": "Public/external URL to view the source item" }, "sourceLastModifiedTime": { "type": "string", "description": "Last-modified timestamp reported by the source provider" }, "isContainer": { "type": "boolean", "description": "Whether this resource is a container (Notion database / Drive folder) that wraps child resources" }, "lastSyncedAt": { "type": "string", "description": "ISO timestamp of the last successful container membership sync" }, "containerSyncOverflowed": { "type": "boolean", "description": "True when the most recent sync stopped creating new children because the workspace resource limit was reached" }, "containerSyncTruncated": { "type": "boolean", "description": "True when the most recent sync listed only a prefix of the source database because it exceeded the per-sync page cap (MAX_PAGES_PER_DATABASE_SYNC). Pages beyond the cap are not indexed and child pruning is skipped for that pass." }, "ignoredChildCount": { "type": "integer", "description": "Container resources: number of source items skipped on the most recent sync because they're nested containers (sub-folders / sub-databases). v1 indexes only top-level items." }, "firstFailedAccessAt": { "type": "string", "description": "ISO timestamp of the first time the source became inaccessible (container 404 / trashed). Stamped on the first FAILED transition and cleared on a successful re-list. Used by the terminal stale-resource prune to measure how long the source has been failing by wall-clock time, since updatedAt is bumped on every re-list." }, "artifactUuid": { "type": "string", "description": "Octave asset resources: the artifact uuid in the octave-artifacts store (container and children)" }, "artifactFilePath": { "type": "string", "description": "Octave asset child resources: path of the indexed file within the artifact (e.g. 'index.html')" }, "artifactVersion": { "type": "integer", "description": "Octave asset container resources: the artifact currentVersion the children were last reconciled against \u2014 the cheap 'anything changed?' gate before per-file hashing" } } }, { "type": "object", "additionalProperties": { "nullable": true } } ] }, { "nullable": true } ] }, "settings": { "anyOf": [ { "allOf": [ { "type": "object", "properties": { "excludeFromReIndexing": { "type": "boolean", "description": "Whether the resource is excluded from re-indexing, can be used for entitlement limits" } } }, { "type": "object", "additionalProperties": { "nullable": true } } ] }, { "nullable": true } ] }, "encodedData": { "type": "string", "nullable": true }, "ragDocumentId": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "pending", "uploading", "indexed", "failed", null ] }, "workspaceOId": { "type": "string" }, "isParentResource": { "type": "boolean" }, "lastIndexedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "hasChildren": { "type": "boolean", "description": "Whether the resource has children, if true use oId to list children resources" }, "totalChildren": { "type": "number", "description": "Total number of children resources" }, "linearChildTypeCounts": { "type": "object", "properties": { "document": { "type": "number" }, "update": { "type": "number" }, "issue": { "type": "number" } }, "required": [ "document", "update", "issue" ], "description": "For Linear containers: child counts grouped by leaf kind (documents / project updates / issues). Legacy issue rows with no leaf kind count as issues." }, "isContainer": { "type": "boolean", "description": "True when this resource is a Notion database / Drive folder wrapper; children are listed via parentResourceOId" }, "lastSyncedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Container resources: timestamp of the last successful membership sync" }, "containerSyncOverflowed": { "type": "boolean", "description": "Container resources: true when sync skipped new children due to workspace resource limit" }, "containerSyncTruncated": { "type": "boolean", "description": "Container resources: true when the source database exceeded the per-sync page cap, so only a prefix was listed/indexed and pruning was skipped" }, "ignoredChildCount": { "type": "integer", "description": "Container resources: number of nested sub-folders / sub-databases skipped on the most recent sync (v1 indexes only top-level items)" }, "parentResourceOId": { "type": "string", "description": "Child resources: oId of the container (Notion database / Drive folder) this resource belongs to. Absent for standalone resources." }, "parentResourceName": { "type": "string", "description": "Child resources: display name of the container, suitable for UI surfacing without an extra fetch." }, "firstFailedAccessAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Container resources: timestamp of the first time the source became inaccessible. Present while the container is FAILED; absent once it recovers." }, "staleContainerPruneEta": { "type": "string", "nullable": true, "format": "date-time", "description": "FAILED container resources: projected date when the container and its children will be terminally pruned (firstFailedAccessAt + the prune window). Drives the 'will be removed in N days' UI warning. Absent for healthy containers." }, "storageData": { "type": "object", "properties": { "taskStatus": { "type": "string", "nullable": true, "enum": [ "pending", "processing", "completed", "failed", null ] }, "ragTaskIdentifier": { "type": "string", "nullable": true }, "filePath": { "type": "string", "nullable": true }, "ragDocumentId": { "type": "string", "nullable": true } } }, "uploadedByUserOId": { "type": "string", "nullable": true } }, "required": [ "oId", "sourceType", "identifier", "workspaceOId", "isParentResource", "createdAt", "updatedAt" ] } }, "total": { "type": "number" }, "hasNext": { "type": "boolean" } }, "required": [ "_metadata", "data", "total", "hasNext" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/resource/create": { "post": { "deprecated": false, "operationId": "createResource", "summary": "Create Resource", "description": "Create a new global resource in the workspace.\n\n**Modes:**\n- `text`: Create from plain text content (sync - returns when indexed)\n- `file`: Create from base64 encoded file (sync - returns when indexed)\n- `url`: Create from URL (async - returns immediately with status: \"pending\")\n- `drive`: Create from Google Drive file ID (async - returns immediately with status: \"pending\")\n- `notion`: Create from Notion page ID (async - returns immediately with status: \"pending\")\n\n**Note:** For `drive` and `notion` modes, the API key must be created by a user with the matching integration connected.\n\n**Async resources:** For `url`, `drive`, and `notion` modes, poll `/resource/status` or `/resource/get?checkStorageTaskStatus=true` to check processing status.", "tags": [ "Resource" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "text" ], "description": "Create a text resource" }, "text": { "type": "string", "minLength": 1, "description": "The text content of the resource", "example": "This is the content of my landing page..." }, "name": { "type": "string", "description": "Display name for the resource", "example": "Product Landing Page" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Optional metadata to attach to the resource", "example": { "customField": "value" } } }, "required": [ "mode", "text" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "file" ], "description": "Create a file resource from base64 encoded content" }, "file": { "type": "string", "description": "Base64 encoded file content", "example": "SGVsbG8gV29ybGQh..." }, "filename": { "type": "string", "description": "Original filename including extension", "example": "document.pdf" }, "contentType": { "type": "string", "description": "MIME type of the file", "example": "application/pdf" }, "name": { "type": "string", "description": "Display name for the resource (defaults to filename)", "example": "Sales Deck Q4" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Optional metadata to attach to the resource", "example": { "customField": "value" } } }, "required": [ "mode", "file", "filename" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "url" ], "description": "Create a resource from a URL (processed asynchronously)" }, "url": { "type": "string", "format": "uri", "description": "URL to crawl and index", "example": "https://example.com/landing-page" }, "name": { "type": "string", "description": "Display name for the resource (defaults to page title)", "example": "Example Landing Page" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Optional metadata to attach to the resource", "example": { "customField": "value" } } }, "required": [ "mode", "url" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "drive" ], "description": "Create a resource from Google Drive (requires connected Drive account)" }, "driveFileId": { "type": "string", "description": "Google Drive file ID", "example": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" }, "name": { "type": "string", "description": "Display name for the resource (defaults to Drive file name)", "example": "Marketing Strategy Doc" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Optional metadata to attach to the resource", "example": { "customField": "value" } } }, "required": [ "mode", "driveFileId" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "notion" ], "description": "Create a resource from a Notion page (requires connected Notion account)" }, "notionPageId": { "type": "string", "description": "Notion page ID", "example": "12345678-90ab-cdef-1234-567890abcdef" }, "name": { "type": "string", "description": "Display name for the resource (defaults to Notion page title)", "example": "ICP Definition" }, "metadata": { "type": "object", "additionalProperties": { "nullable": true }, "description": "Optional metadata to attach to the resource", "example": { "customField": "value" } } }, "required": [ "mode", "notionPageId" ] } ] } } } }, "responses": { "200": { "description": "Resource created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "sourceType": { "type": "string", "enum": [ "url", "google_drive", "notion", "linear", "text", "octave_asset" ] }, "name": { "type": "string", "nullable": true }, "identifier": { "type": "string" }, "sourceUrl": { "type": "string", "description": "External deep link to view the source item, across all source types: the provider URL for Drive/Notion/Linear resources, the page URL for website (url) resources. Absent for sources with no external surface (text, file uploads)." }, "metadata": { "anyOf": [ { "allOf": [ { "type": "object", "properties": { "ragTaskIdentifier": { "type": "string" }, "taskStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ] }, "externalFilePath": { "type": "string", "description": "File path in fieldwise, use this to download the file from fieldwise" }, "title": { "type": "string" }, "description": { "type": "string" }, "faviconUrl": { "type": "string" }, "logoUrl": { "type": "string" }, "statusCode": { "type": "number" }, "isWorkspacePrimarySource": { "type": "boolean", "description": "Whether the resource is the primary source for the workspace" }, "isMainResource": { "type": "boolean", "description": "Entry point of resource tree" }, "asyncCrawlComplete": { "type": "boolean", "description": "Whether async crawl for child pages has completed (for main website resources)" }, "crawlQueuedAt": { "type": "string", "description": "ISO timestamp of when the most recent async child-page crawl was queued. Lets the UI distinguish an in-flight crawl (recent) from a stuck one (old) while asyncCrawlComplete is false." }, "originalFileName": { "type": "string", "description": "Original file name for file uploads" }, "sourceItemType": { "type": "string", "enum": [ "file", "folder" ], "description": "Whether the source item is a leaf (file / page) or a container (folder / database)" }, "sourceItemUrl": { "type": "string", "description": "Public/external URL to view the source item" }, "sourceLastModifiedTime": { "type": "string", "description": "Last-modified timestamp reported by the source provider" }, "isContainer": { "type": "boolean", "description": "Whether this resource is a container (Notion database / Drive folder) that wraps child resources" }, "lastSyncedAt": { "type": "string", "description": "ISO timestamp of the last successful container membership sync" }, "containerSyncOverflowed": { "type": "boolean", "description": "True when the most recent sync stopped creating new children because the workspace resource limit was reached" }, "containerSyncTruncated": { "type": "boolean", "description": "True when the most recent sync listed only a prefix of the source database because it exceeded the per-sync page cap (MAX_PAGES_PER_DATABASE_SYNC). Pages beyond the cap are not indexed and child pruning is skipped for that pass." }, "ignoredChildCount": { "type": "integer", "description": "Container resources: number of source items skipped on the most recent sync because they're nested containers (sub-folders / sub-databases). v1 indexes only top-level items." }, "firstFailedAccessAt": { "type": "string", "description": "ISO timestamp of the first time the source became inaccessible (container 404 / trashed). Stamped on the first FAILED transition and cleared on a successful re-list. Used by the terminal stale-resource prune to measure how long the source has been failing by wall-clock time, since updatedAt is bumped on every re-list." }, "artifactUuid": { "type": "string", "description": "Octave asset resources: the artifact uuid in the octave-artifacts store (container and children)" }, "artifactFilePath": { "type": "string", "description": "Octave asset child resources: path of the indexed file within the artifact (e.g. 'index.html')" }, "artifactVersion": { "type": "integer", "description": "Octave asset container resources: the artifact currentVersion the children were last reconciled against \u2014 the cheap 'anything changed?' gate before per-file hashing" } } }, { "type": "object", "additionalProperties": { "nullable": true } } ] }, { "nullable": true } ] }, "settings": { "anyOf": [ { "allOf": [ { "type": "object", "properties": { "excludeFromReIndexing": { "type": "boolean", "description": "Whether the resource is excluded from re-indexing, can be used for entitlement limits" } } }, { "type": "object", "additionalProperties": { "nullable": true } } ] }, { "nullable": true } ] }, "encodedData": { "type": "string", "nullable": true }, "ragDocumentId": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true, "enum": [ "pending", "uploading", "indexed", "failed", null ] }, "workspaceOId": { "type": "string" }, "isParentResource": { "type": "boolean" }, "isGlobal": { "type": "boolean" }, "lastIndexedAt": { "type": "string", "nullable": true, "format": "date-time" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "hasChildren": { "type": "boolean", "description": "Whether the resource has children, if true use oId to list children resources" }, "totalChildren": { "type": "number", "description": "Total number of children resources" }, "linearChildTypeCounts": { "type": "object", "properties": { "document": { "type": "number" }, "update": { "type": "number" }, "issue": { "type": "number" } }, "required": [ "document", "update", "issue" ], "description": "For Linear containers: child counts grouped by leaf kind (documents / project updates / issues). Legacy issue rows with no leaf kind count as issues." }, "isContainer": { "type": "boolean", "description": "True when this resource is a Notion database / Drive folder wrapper; children are listed via parentResourceOId" }, "lastSyncedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Container resources: timestamp of the last successful membership sync" }, "containerSyncOverflowed": { "type": "boolean", "description": "Container resources: true when sync skipped new children due to workspace resource limit" }, "containerSyncTruncated": { "type": "boolean", "description": "Container resources: true when the source database exceeded the per-sync page cap, so only a prefix was listed/indexed and pruning was skipped" }, "ignoredChildCount": { "type": "integer", "description": "Container resources: number of nested sub-folders / sub-databases skipped on the most recent sync (v1 indexes only top-level items)" }, "parentResourceOId": { "type": "string", "description": "Child resources: oId of the container (Notion database / Drive folder) this resource belongs to. Absent for standalone resources." }, "parentResourceName": { "type": "string", "description": "Child resources: display name of the container, suitable for UI surfacing without an extra fetch." }, "firstFailedAccessAt": { "type": "string", "nullable": true, "format": "date-time", "description": "Container resources: timestamp of the first time the source became inaccessible. Present while the container is FAILED; absent once it recovers." }, "staleContainerPruneEta": { "type": "string", "nullable": true, "format": "date-time", "description": "FAILED container resources: projected date when the container and its children will be terminally pruned (firstFailedAccessAt + the prune window). Drives the 'will be removed in N days' UI warning. Absent for healthy containers." }, "storageData": { "type": "object", "properties": { "taskStatus": { "type": "string", "nullable": true, "enum": [ "pending", "processing", "completed", "failed", null ] }, "ragTaskIdentifier": { "type": "string", "nullable": true }, "filePath": { "type": "string", "nullable": true }, "ragDocumentId": { "type": "string", "nullable": true } } }, "uploadedByUserOId": { "type": "string", "nullable": true } }, "required": [ "oId", "sourceType", "identifier", "workspaceOId", "isParentResource", "isGlobal", "createdAt", "updatedAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request (e.g., Google Drive not connected)", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "402": { "description": "Resource limit exceeded", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/resource/status": { "get": { "deprecated": false, "operationId": "getResourceStatus", "summary": "Get Resource Status", "description": "Get the current processing status of a resource. Use this to poll for completion after creating async resources (URL or drive mode).", "tags": [ "Resource" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Resource OId", "example": "res_abc123" }, "required": true, "description": "Resource OId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Resource status", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string", "description": "Resource OId" }, "status": { "type": "string", "nullable": true, "enum": [ "pending", "uploading", "indexed", "failed", null ], "description": "Current resource status: PENDING, UPLOADING, INDEXED, or FAILED" }, "storageData": { "type": "object", "properties": { "taskStatus": { "type": "string", "nullable": true, "enum": [ "pending", "processing", "completed", "failed", null ], "description": "RAG task status if applicable" }, "ragTaskIdentifier": { "type": "string", "nullable": true, "description": "RAG task identifier for tracking" } }, "description": "Storage task details from RAG" } }, "required": [ "oId" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/resource/delete": { "post": { "deprecated": false, "operationId": "deleteResources", "summary": "Delete Resource(s)", "description": "Soft delete one or more resources. Provide either a single oId or an array of oIds.", "tags": [ "Resource" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "Resource OId to delete (use either oId or oIds)", "example": "res_abc123" }, "oIds": { "type": "array", "items": { "type": "string" }, "description": "Array of resource OIds to delete (use either oId or oIds)", "example": [ "res_abc123", "res_def456" ] } } } } } }, "responses": { "200": { "description": "Resources deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "deleted": { "type": "number", "description": "Number of resources deleted", "example": 1 } }, "required": [ "deleted" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/resource/search": { "post": { "deprecated": false, "operationId": "searchResources", "summary": "Search Resources", "description": "Search across global resources using semantic search. Returns resources ranked by relevance to the query.", "tags": [ "Resource" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Search query for semantic search across resources", "example": "pricing strategies for enterprise customers" }, "limit": { "type": "number", "default": 10, "description": "Maximum number of results to return (default: 10)", "example": 10 } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string", "description": "Resource OId" }, "name": { "type": "string", "description": "Resource name" }, "url": { "type": "string", "nullable": true, "description": "URL if this is a URL resource" }, "content": { "type": "string", "nullable": true, "description": "Matching content excerpt" }, "score": { "type": "number", "nullable": true, "description": "Relevance score" } }, "required": [ "oId", "name" ] } }, "total": { "type": "number" } }, "required": [ "_metadata", "data", "total" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/skill/list": { "get": { "deprecated": false, "operationId": "listSkills", "summary": "List Skills", "description": "List the workspace's skills (agent instruction documents) with status and text filters. Returns L1 metadata (names and descriptions) without bodies.", "tags": [ "Skill" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "draft", "published" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "me" ] }, "required": false, "name": "owner", "in": "query" }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] }, "required": false, "name": "active", "in": "query" }, { "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "default": false }, "required": false, "name": "includeArchived", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Skills listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 1024, "description": "L1 metadata: what the skill does and when to use it \u2014 the retrieval trigger text" }, "artifactUuid": { "type": "string", "description": "Backing folder in the octave-artifacts store" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "sourceType": { "type": "string", "nullable": true, "enum": [ "authored", "imported", "generated", "uploaded", null ] }, "sourceMetadata": { "type": "object", "nullable": true, "properties": { "resourceOId": { "type": "string" }, "url": { "type": "string" }, "eventOIds": { "type": "array", "items": { "type": "string" } }, "findingOIds": { "type": "array", "items": { "type": "string" } }, "exampleCount": { "type": "number" } }, "additionalProperties": { "nullable": true } }, "active": { "type": "boolean" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lockedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lockedByUser": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" } }, "required": [ "oId", "name", "description", "artifactUuid", "status", "active", "createdAt" ] } }, "total": { "type": "number" }, "hasNext": { "type": "boolean" } }, "required": [ "_metadata", "data", "total", "hasNext" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/skill/get": { "get": { "deprecated": false, "operationId": "getSkill", "summary": "Get Skill", "description": "Get a skill by oId or by its exact name (unique per workspace), including its SKILL.md markdown body and bundled-file listing.", "tags": [ "Skill" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Skill oId. Provide this or `name`.", "example": "skl_abc123" }, "required": false, "description": "Skill oId. Provide this or `name`.", "name": "oId", "in": "query" }, { "schema": { "type": "string", "description": "The skill's exact name slug (unique per workspace). Provide this or `oId`.", "example": "meeting-prep" }, "required": false, "description": "The skill's exact name slug (unique per workspace). Provide this or `oId`.", "name": "name", "in": "query" } ], "responses": { "200": { "description": "Skill retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 1024, "description": "L1 metadata: what the skill does and when to use it \u2014 the retrieval trigger text" }, "content": { "type": "string", "description": "Markdown body of SKILL.md (below the frontmatter)" }, "contentJson": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "artifactUuid": { "type": "string", "description": "Backing folder in the octave-artifacts store" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "sourceType": { "type": "string", "nullable": true, "enum": [ "authored", "imported", "generated", "uploaded", null ] }, "sourceMetadata": { "type": "object", "nullable": true, "properties": { "resourceOId": { "type": "string" }, "url": { "type": "string" }, "eventOIds": { "type": "array", "items": { "type": "string" } }, "findingOIds": { "type": "array", "items": { "type": "string" } }, "exampleCount": { "type": "number" } }, "additionalProperties": { "nullable": true } }, "active": { "type": "boolean" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lockedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lockedByUser": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "number" }, "mimeType": { "type": "string" } }, "required": [ "path", "size", "mimeType" ] } } }, "required": [ "oId", "name", "description", "content", "artifactUuid", "status", "active", "createdAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/skill/create": { "post": { "deprecated": false, "operationId": "createSkill", "summary": "Create Skill", "description": "Create a skill from frontmatter fields (name, description) and a markdown body. The composed SKILL.md is stored in the artifact store; new skills start as DRAFT until published. The API key's creating user must be a workspace or organization owner.", "tags": [ "Skill" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 1024, "default": "" }, "content": { "type": "string", "default": "" }, "contentJson": { "type": "object", "additionalProperties": { "nullable": true } }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "sourceType": { "type": "string", "enum": [ "authored", "imported", "generated", "uploaded" ] }, "sourceMetadata": { "type": "object", "properties": { "resourceOId": { "type": "string" }, "url": { "type": "string" }, "eventOIds": { "type": "array", "items": { "type": "string" } }, "findingOIds": { "type": "array", "items": { "type": "string" } }, "exampleCount": { "type": "number" } }, "additionalProperties": { "nullable": true } } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Skill created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 1024, "description": "L1 metadata: what the skill does and when to use it \u2014 the retrieval trigger text" }, "content": { "type": "string", "description": "Markdown body of SKILL.md (below the frontmatter)" }, "contentJson": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "artifactUuid": { "type": "string", "description": "Backing folder in the octave-artifacts store" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "sourceType": { "type": "string", "nullable": true, "enum": [ "authored", "imported", "generated", "uploaded", null ] }, "sourceMetadata": { "type": "object", "nullable": true, "properties": { "resourceOId": { "type": "string" }, "url": { "type": "string" }, "eventOIds": { "type": "array", "items": { "type": "string" } }, "findingOIds": { "type": "array", "items": { "type": "string" } }, "exampleCount": { "type": "number" } }, "additionalProperties": { "nullable": true } }, "active": { "type": "boolean" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lockedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lockedByUser": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "number" }, "mimeType": { "type": "string" } }, "required": [ "path", "size", "mimeType" ] } } }, "required": [ "oId", "name", "description", "content", "artifactUuid", "status", "active", "createdAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/skill/update": { "post": { "deprecated": false, "operationId": "updateSkill", "summary": "Update Skill", "description": "Update a skill's frontmatter (name/description), SKILL.md body, or publication state. Content edits rewrite the stored SKILL.md; the store keeps version history. The API key's creating user must be a workspace or organization owner.", "tags": [ "Skill" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 1024 }, "content": { "type": "string" }, "contentJson": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "active": { "type": "boolean" }, "archived": { "type": "boolean" }, "writeBatchId": { "type": "string", "pattern": "^[A-Za-z0-9._~-]{1,200}$" } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Skill updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 1024, "description": "L1 metadata: what the skill does and when to use it \u2014 the retrieval trigger text" }, "content": { "type": "string", "description": "Markdown body of SKILL.md (below the frontmatter)" }, "contentJson": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true } }, "artifactUuid": { "type": "string", "description": "Backing folder in the octave-artifacts store" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "sourceType": { "type": "string", "nullable": true, "enum": [ "authored", "imported", "generated", "uploaded", null ] }, "sourceMetadata": { "type": "object", "nullable": true, "properties": { "resourceOId": { "type": "string" }, "url": { "type": "string" }, "eventOIds": { "type": "array", "items": { "type": "string" } }, "findingOIds": { "type": "array", "items": { "type": "string" } }, "exampleCount": { "type": "number" } }, "additionalProperties": { "nullable": true } }, "active": { "type": "boolean" }, "archivedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lockedAt": { "type": "string", "nullable": true, "format": "date-time" }, "lockedByUser": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "user": { "type": "object", "nullable": true, "properties": { "oId": { "type": "string" }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true } }, "required": [ "oId" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "nullable": true, "format": "date-time" }, "files": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "path": { "type": "string" }, "size": { "type": "number" }, "mimeType": { "type": "string" } }, "required": [ "path", "size", "mimeType" ] } } }, "required": [ "oId", "name", "description", "content", "artifactUuid", "status", "active", "createdAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/skill/delete": { "post": { "deprecated": false, "operationId": "deleteSkill", "summary": "Delete Skill", "description": "Delete a skill: soft-deletes the registry entry and removes its stored folder. The API key's creating user must be a workspace or organization owner.", "tags": [ "Skill" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "Skill oId", "example": "skl_abc123" } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Skill deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/skill/find": { "post": { "deprecated": false, "operationId": "findSkill", "summary": "Find Skill", "description": "Resolve a task to the best-fitting skills via multi-strategy retrieval (full-text + semantic) plus an LLM reasoning step. Returns ranked candidates with reasoning and confidence, without bodies \u2014 fetch the chosen skill via Get Skill. Zero results means no skill fits; proceed with a default approach.", "tags": [ "Skill" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "task": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "The generation task to resolve, e.g. \"prep me for a discovery call with an enterprise CTO\"" }, "limit": { "type": "integer", "minimum": 1, "maximum": 5, "default": 3 } }, "required": [ "task" ] } } } }, "responses": { "200": { "description": "Candidates ranked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "description": { "type": "string", "maxLength": 1024 }, "confidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "reasoning": { "type": "string", "nullable": true } }, "required": [ "oId", "name", "description", "confidence" ] } }, "noMatch": { "type": "boolean" } }, "required": [ "results", "noMatch" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/skill/file": { "get": { "deprecated": false, "operationId": "getSkillFile", "summary": "Get Skill File", "description": "Read one bundled file of a skill (progressive disclosure level 3). Use the paths from Get Skill's files listing. Fetch files only when the SKILL.md instructions reference them for the task at hand.", "tags": [ "Skill" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Skill oId", "example": "skl_abc123" }, "required": true, "description": "Skill oId", "name": "oId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Root-relative file path from Get Skill's files listing, e.g. references/objection-handling.md", "example": "references/objection-handling.md" }, "required": true, "description": "Root-relative file path from Get Skill's files listing, e.g. references/objection-handling.md", "name": "path", "in": "query" } ], "responses": { "200": { "description": "Skill file retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string", "description": "The file's text content" } }, "required": [ "path", "content" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/list": { "get": { "deprecated": false, "operationId": "listAssets", "summary": "List Assets", "description": "List the calling user's assets (hosted sites, storage bundles, and managed skill folders). Optionally filter by status, privacy, owner, or a search string, and page through results with limit/offset.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Max assets to return, 1\u2013100. e.g. 20" }, "required": false, "description": "Max assets to return, 1\u2013100. e.g. 20", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "How many assets to skip, for pagination. e.g. 0" }, "required": false, "description": "How many assets to skip, for pagination. e.g. 0", "name": "offset", "in": "query" }, { "schema": { "type": "string", "enum": [ "published", "unpublished" ], "description": "Filter by lifecycle status; omit for all. One of: published, unpublished. e.g. 'published'" }, "required": false, "description": "Filter by lifecycle status; omit for all. One of: published, unpublished. e.g. 'published'", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "only_me", "workspace", "public" ], "description": "Filter by privacy; omit for all. One of: only_me, workspace, public. e.g. 'public'" }, "required": false, "description": "Filter by privacy; omit for all. One of: only_me, workspace, public. e.g. 'public'", "name": "privacy", "in": "query" }, { "schema": { "type": "string", "maxLength": 255, "description": "Server-side case-insensitive substring match across identifier, description, and vanitySlug \u2014 use this to check whether something is already published before creating it. Applied before pagination, so total reflects matches. e.g. 'q3 deck'" }, "required": false, "description": "Server-side case-insensitive substring match across identifier, description, and vanitySlug \u2014 use this to check whether something is already published before creating it. Applied before pagination, so total reflects matches. e.g. 'q3 deck'", "name": "search", "in": "query" }, { "schema": { "type": "string", "format": "email", "description": "Only assets owned by this workspace member (within what you can already see \u2014 never widens access). e.g. 'sam@acme.com'" }, "required": false, "description": "Only assets owned by this workspace member (within what you can already see \u2014 never widens access). e.g. 'sam@acme.com'", "name": "ownerEmail", "in": "query" } ], "responses": { "200": { "description": "Assets listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } }, "total": { "type": "number" }, "hasNext": { "type": "boolean" } }, "required": [ "_metadata", "data", "total", "hasNext" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/get": { "get": { "deprecated": false, "operationId": "getAsset", "summary": "Get Asset", "description": "Fetch a single asset by its UUID, including its metadata, flat file list, and site directory tree. Use List Assets first if you don't have the UUID.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "required": true, "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'", "name": "uuid", "in": "query" } ], "responses": { "200": { "description": "Asset retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Asset" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/update": { "post": { "deprecated": false, "operationId": "updateAsset", "summary": "Update Asset", "description": "Update an asset's editable fields \u2014 any of identifier, description, entry point, privacy, status, and vanitySlug. privacy and status are independent: publishing does NOT make an asset public \u2014 set privacy to 'public' for that. vanitySlug claims a workspace-unique friendly URL (409 if taken; null clears it). Provide the uuid plus at least one field to change; returns the updated asset.", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset to update. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "identifier": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New identifier/slug. e.g. 'q3-launch-microsite'" }, "description": { "type": "string", "minLength": 1, "description": "New description. e.g. 'Updated Q3 launch page'" }, "entryPoint": { "type": "string", "minLength": 1, "maxLength": 255, "description": "New entry file served at the root. e.g. 'index.html'" }, "privacy": { "type": "string", "enum": [ "only_me", "workspace", "public" ], "description": "New privacy tier \u2014 an ordered ladder, each strictly more permissive: only_me (owner only), workspace (owner + workspace members), public (anyone with the URL). e.g. 'public'" }, "status": { "type": "string", "enum": [ "published", "unpublished" ], "description": "New lifecycle status. One of: published, unpublished. Independent of privacy \u2014 this does NOT make an asset public or private; use privacy for that. e.g. 'published'" }, "vanitySlug": { "type": "string", "nullable": true, "minLength": 1, "description": "Vanity slug for a friendly URL \u2014 unique within the workspace; the server answers 409 (conflict) when another asset already holds it. Setting one gives the asset a vanityUrl; pass null to clear the slug (and its vanityUrl). e.g. 'q3-launch'" } }, "required": [ "uuid" ] } } } }, "responses": { "200": { "description": "Asset updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Asset" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/delete": { "delete": { "deprecated": false, "operationId": "deleteAsset", "summary": "Delete Asset", "description": "Permanently delete an asset and its stored files by UUID. This cannot be undone. A managed skill's backing folder is refused here \u2014 delete the skill via the Skill API instead, so its searchable registry entry stays in sync.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "required": true, "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'", "name": "uuid", "in": "query" } ], "responses": { "200": { "description": "Asset deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True when the asset was deleted. e.g. true" }, "uuid": { "type": "string", "description": "UUID of the deleted asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" } }, "required": [ "success", "uuid" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/stats": { "get": { "deprecated": false, "operationId": "getStats", "summary": "Get Asset Stats", "description": "Get per-day unique visit and download counts for an asset. Owner-only analytics: works for your own assets; a teammate can read a shared asset but never its analytics. For WHO opened it (identified viewers), use List Asset Visitors instead.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "required": true, "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'", "name": "uuid", "in": "query" } ], "responses": { "200": { "description": "Asset stats retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Day the counts cover, YYYY-MM-DD. e.g. '2026-07-10'" }, "totalUniqueVisits": { "type": "number", "description": "All unique visit-days, external plus workspace. e.g. 14" }, "externalUniqueVisits": { "type": "number", "default": 0, "description": "Public and share-link unique visit-days. e.g. 9" }, "workspaceUniqueVisits": { "type": "number", "default": 0, "description": "Verified workspace-member unique visit-days. e.g. 5" }, "totalUniqueDownloads": { "type": "number", "description": "All unique download-days, external plus workspace. e.g. 3" }, "externalUniqueDownloads": { "type": "number", "default": 0, "description": "Public and share-link unique download-days. e.g. 2" }, "workspaceUniqueDownloads": { "type": "number", "default": 0, "description": "Verified workspace-member unique download-days. e.g. 1" } }, "required": [ "date", "totalUniqueVisits", "totalUniqueDownloads" ] }, "description": "Per-day unique visit and download counts for the asset." } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/visitors": { "get": { "deprecated": false, "operationId": "listVisitors", "summary": "List Asset Visitors", "description": "List the identified viewers of an asset \u2014 every code-verified viewer with open counts and first/last-seen times: share-link recipients (via 'share') and workspace-verified members (via 'workspace'). Anonymous public visitors never appear here \u2014 use Get Asset Stats for aggregate counts. Owner-only analytics, like Get Asset Stats.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "required": true, "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'", "name": "uuid", "in": "query" } ], "responses": { "200": { "description": "Asset visitors listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Viewer's code-verified email. e.g. 'sam@acme.com'" }, "via": { "type": "string", "enum": [ "share", "workspace" ], "description": "How the viewer got access. One of: share (a share-link recipient), workspace (a workspace-verified member). e.g. 'share'" }, "openCount": { "type": "number", "description": "How many times they opened the asset. e.g. 2" }, "firstSeenAt": { "type": "string", "description": "ISO-8601 time of their first open. e.g. '2026-07-08T15:00:00.000Z'" }, "lastSeenAt": { "type": "string", "description": "ISO-8601 time of their most recent open. e.g. '2026-07-11T09:45:00.000Z'" } }, "required": [ "email", "via", "openCount", "firstSeenAt", "lastSeenAt" ] } }, "total": { "type": "number" } }, "required": [ "_metadata", "data", "total" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/versions/list": { "get": { "deprecated": false, "operationId": "listVersions", "summary": "List Asset Versions", "description": "List an asset's version history, newest first. Every file update mints an immutable version; 'current' marks the one the asset's URL serves and latestVersion is the mint high-water mark (they differ after a rollback). Use before Restore Asset Version or Delete Asset Version to pick a version number.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "required": true, "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'", "name": "uuid", "in": "query" } ], "responses": { "200": { "description": "Asset versions listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "number", "description": "Version number \u2014 never reused, even after deletion. e.g. 3" }, "current": { "type": "boolean", "description": "True when this is the version the asset's URL serves. e.g. true" }, "note": { "type": "string", "nullable": true, "description": "Optional note recorded when the version was minted; null when none. e.g. 'Fixed pricing table'" }, "fileCount": { "type": "number", "description": "Number of files in the snapshot. e.g. 12" }, "totalSize": { "type": "number", "description": "Total size of the snapshot in bytes. e.g. 348160" }, "createdAt": { "type": "string", "description": "ISO-8601 time the version was minted. e.g. '2026-07-09T10:00:00.000Z'" } }, "required": [ "version", "current", "note", "fileCount", "totalSize", "createdAt" ] } }, "currentVersion": { "type": "number" }, "latestVersion": { "type": "number" }, "total": { "type": "number" } }, "required": [ "_metadata", "data", "currentVersion", "latestVersion", "total" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/versions/restore": { "post": { "deprecated": false, "operationId": "restoreVersion", "summary": "Restore Asset Version", "description": "Roll an asset back to a previous version \u2014 an instant pointer flip: the asset's URL serves the chosen snapshot immediately, no files move, and newer versions are NOT deleted (they stay restorable, so you can roll forward again the same way). Returns the updated asset with currentVersion set to the restored version. A managed skill's backing folder is refused here \u2014 edit the skill via the Skill API instead.", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "version": { "type": "integer", "minimum": 1, "description": "Version number, from asset_versions_list. e.g. 2" } }, "required": [ "uuid", "version" ] } } } }, "responses": { "200": { "description": "Asset version restored successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Asset" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/versions/delete": { "delete": { "deprecated": false, "operationId": "deleteVersion", "summary": "Delete Asset Version", "description": "Permanently delete a version's snapshot files (storage cleanup). This cannot be undone \u2014 the version stops being restorable. The CURRENT version can never be deleted (the server answers 400); restore a different version first. Version numbers are never reused.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "required": true, "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'", "name": "uuid", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "description": "Version number, from asset_versions_list. e.g. 2" }, "required": true, "description": "Version number, from asset_versions_list. e.g. 2", "name": "version", "in": "query" } ], "responses": { "200": { "description": "Asset version deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True when the version snapshot was deleted. e.g. true" }, "uuid": { "type": "string", "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "version": { "type": "number", "description": "The deleted version number. e.g. 2" } }, "required": [ "success", "uuid", "version" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/shares/list": { "get": { "deprecated": false, "operationId": "listShares", "summary": "List Asset Shares", "description": "List an asset's share links, each with its email/domain allowlist and expiry. The share UUIDs returned here are what Revoke Asset Share and the recipient/domain endpoints take.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "required": true, "description": "Asset UUID, from assets_list. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'", "name": "uuid", "in": "query" } ], "responses": { "200": { "description": "Asset shares listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Share link UUID \u2014 the id used by asset_share_* tools. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "url": { "type": "string", "nullable": true, "description": "The share URL to send recipients; re-readable, so it can be copied again any time. Null only for legacy shares minted before recoverable link storage \u2014 asset_share_rotate mints those a fresh one. e.g. 'https://sites.octave.app/s/eyJ...'" }, "access": { "type": "string", "enum": [ "allowlist", "anyone" ], "description": "The link's gate. 'allowlist' (the default) makes a viewer prove an allowlisted email \u2014 or a mailbox at an allowlisted domain \u2014 with a one-time code, and attributes the visit to them. 'anyone' means holding the link IS the credential: no check, and the visit is counted but attributed to nobody. e.g. 'allowlist'" }, "expiresAt": { "type": "string", "nullable": true, "description": "ISO-8601 expiry; null means it never expires. e.g. '2026-08-06T00:00:00.000Z'" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted exact recipient emails. e.g. ['sam@acme.com']" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted domains \u2014 any verified mailbox at these gets access. e.g. ['acme.com']" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-06T09:00:00.000Z'" } }, "required": [ "uuid", "url", "access", "expiresAt", "emails", "domains", "createdAt" ] } }, "total": { "type": "number" } }, "required": [ "_metadata", "data", "total" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/shares/create": { "post": { "deprecated": false, "operationId": "createShare", "summary": "Create Asset Share", "description": "Create an email-verified share link for an asset. Allowlist by exact emails and/or whole domains \u2014 provide at least one entry across the two. Set expiresInDays (1\u20133650) or null for a link that never expires. The returned url embeds the link token; it stays readable via List Asset Shares, so it can be copied again later.", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset to share. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "expiresInDays": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 3650, "description": "Days until the link expires, 1\u20133650; or null for never. e.g. 30" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Exact recipient emails to allow. Provide emails and/or domains \u2014 at least one across the two is required. e.g. ['sam@acme.com']" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Domains to allow (any verified mailbox at the domain). Provide emails and/or domains \u2014 at least one across the two is required. e.g. ['acme.com']" } }, "required": [ "uuid", "expiresInDays" ] } } } }, "responses": { "200": { "description": "Asset share created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Share link UUID \u2014 the id used by asset_share_* tools. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "url": { "type": "string", "description": "The share URL embedding the link token. Always present here, and re-readable later via asset_shares_list. e.g. 'https://sites.octave.app/s/eyJ...'" }, "access": { "type": "string", "enum": [ "allowlist", "anyone" ], "description": "The link's gate. 'allowlist' (the default) makes a viewer prove an allowlisted email \u2014 or a mailbox at an allowlisted domain \u2014 with a one-time code, and attributes the visit to them. 'anyone' means holding the link IS the credential: no check, and the visit is counted but attributed to nobody. e.g. 'allowlist'" }, "expiresAt": { "type": "string", "nullable": true, "description": "ISO-8601 expiry; null means it never expires. e.g. '2026-08-06T00:00:00.000Z'" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted exact recipient emails. e.g. ['sam@acme.com']" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted domains \u2014 any verified mailbox at these gets access. e.g. ['acme.com']" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-06T09:00:00.000Z'" } }, "required": [ "uuid", "url", "access", "expiresAt", "emails", "domains", "createdAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/shares/revoke": { "delete": { "deprecated": false, "operationId": "revokeShare", "summary": "Revoke Asset Share", "description": "Revoke a share link by its UUID. Any active viewer sessions are cut off immediately. This cannot be undone.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "required": true, "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'", "name": "uuid", "in": "query" }, { "schema": { "type": "string", "description": "UUID of the share link, from asset_shares_list. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "required": true, "description": "UUID of the share link, from asset_shares_list. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'", "name": "shareUuid", "in": "query" } ], "responses": { "200": { "description": "Asset share revoked successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "success": { "type": "boolean", "description": "True when the share link was revoked. e.g. true" }, "shareUuid": { "type": "string", "description": "UUID of the revoked share link. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" } }, "required": [ "success", "shareUuid" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/shares/add-recipients": { "post": { "deprecated": false, "operationId": "addShareRecipients", "summary": "Add Asset Share Recipients", "description": "Add exact recipient emails to an existing share link's allowlist. Already-present emails are ignored. Returns the updated share.", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "shareUuid": { "type": "string", "description": "UUID of the share link, from asset_shares_list. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "emails": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Recipient emails to add or remove. e.g. ['sam@acme.com']" } }, "required": [ "uuid", "shareUuid", "emails" ] } } } }, "responses": { "200": { "description": "Share recipients added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Share link UUID \u2014 the id used by asset_share_* tools. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "url": { "type": "string", "nullable": true, "description": "The share URL to send recipients; re-readable, so it can be copied again any time. Null only for legacy shares minted before recoverable link storage \u2014 asset_share_rotate mints those a fresh one. e.g. 'https://sites.octave.app/s/eyJ...'" }, "access": { "type": "string", "enum": [ "allowlist", "anyone" ], "description": "The link's gate. 'allowlist' (the default) makes a viewer prove an allowlisted email \u2014 or a mailbox at an allowlisted domain \u2014 with a one-time code, and attributes the visit to them. 'anyone' means holding the link IS the credential: no check, and the visit is counted but attributed to nobody. e.g. 'allowlist'" }, "expiresAt": { "type": "string", "nullable": true, "description": "ISO-8601 expiry; null means it never expires. e.g. '2026-08-06T00:00:00.000Z'" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted exact recipient emails. e.g. ['sam@acme.com']" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted domains \u2014 any verified mailbox at these gets access. e.g. ['acme.com']" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-06T09:00:00.000Z'" } }, "required": [ "uuid", "url", "access", "expiresAt", "emails", "domains", "createdAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/shares/remove-recipients": { "post": { "deprecated": false, "operationId": "removeShareRecipients", "summary": "Remove Asset Share Recipients", "description": "Remove recipient emails from an existing share link's allowlist. Removed viewers lose access on their next visit. Emails not on the allowlist are ignored. Returns the updated share.", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "shareUuid": { "type": "string", "description": "UUID of the share link, from asset_shares_list. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "emails": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Recipient emails to add or remove. e.g. ['sam@acme.com']" } }, "required": [ "uuid", "shareUuid", "emails" ] } } } }, "responses": { "200": { "description": "Share recipients removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Share link UUID \u2014 the id used by asset_share_* tools. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "url": { "type": "string", "nullable": true, "description": "The share URL to send recipients; re-readable, so it can be copied again any time. Null only for legacy shares minted before recoverable link storage \u2014 asset_share_rotate mints those a fresh one. e.g. 'https://sites.octave.app/s/eyJ...'" }, "access": { "type": "string", "enum": [ "allowlist", "anyone" ], "description": "The link's gate. 'allowlist' (the default) makes a viewer prove an allowlisted email \u2014 or a mailbox at an allowlisted domain \u2014 with a one-time code, and attributes the visit to them. 'anyone' means holding the link IS the credential: no check, and the visit is counted but attributed to nobody. e.g. 'allowlist'" }, "expiresAt": { "type": "string", "nullable": true, "description": "ISO-8601 expiry; null means it never expires. e.g. '2026-08-06T00:00:00.000Z'" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted exact recipient emails. e.g. ['sam@acme.com']" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted domains \u2014 any verified mailbox at these gets access. e.g. ['acme.com']" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-06T09:00:00.000Z'" } }, "required": [ "uuid", "url", "access", "expiresAt", "emails", "domains", "createdAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/shares/add-domains": { "post": { "deprecated": false, "operationId": "addShareDomains", "summary": "Add Asset Share Domains", "description": "Add domains to an existing share link's allowlist \u2014 any verified mailbox at an allowlisted domain gets access. Already-present domains are ignored. Returns the updated share.", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "shareUuid": { "type": "string", "description": "UUID of the share link, from asset_shares_list. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "domains": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Domains to add or remove. e.g. ['acme.com']" } }, "required": [ "uuid", "shareUuid", "domains" ] } } } }, "responses": { "200": { "description": "Share domains added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Share link UUID \u2014 the id used by asset_share_* tools. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "url": { "type": "string", "nullable": true, "description": "The share URL to send recipients; re-readable, so it can be copied again any time. Null only for legacy shares minted before recoverable link storage \u2014 asset_share_rotate mints those a fresh one. e.g. 'https://sites.octave.app/s/eyJ...'" }, "access": { "type": "string", "enum": [ "allowlist", "anyone" ], "description": "The link's gate. 'allowlist' (the default) makes a viewer prove an allowlisted email \u2014 or a mailbox at an allowlisted domain \u2014 with a one-time code, and attributes the visit to them. 'anyone' means holding the link IS the credential: no check, and the visit is counted but attributed to nobody. e.g. 'allowlist'" }, "expiresAt": { "type": "string", "nullable": true, "description": "ISO-8601 expiry; null means it never expires. e.g. '2026-08-06T00:00:00.000Z'" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted exact recipient emails. e.g. ['sam@acme.com']" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted domains \u2014 any verified mailbox at these gets access. e.g. ['acme.com']" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-06T09:00:00.000Z'" } }, "required": [ "uuid", "url", "access", "expiresAt", "emails", "domains", "createdAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/shares/remove-domains": { "post": { "deprecated": false, "operationId": "removeShareDomains", "summary": "Remove Asset Share Domains", "description": "Remove domains from an existing share link's allowlist. Viewers who only had domain-based access lose it on their next visit. Domains not on the allowlist are ignored. Returns the updated share.", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "shareUuid": { "type": "string", "description": "UUID of the share link, from asset_shares_list. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "domains": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Domains to add or remove. e.g. ['acme.com']" } }, "required": [ "uuid", "shareUuid", "domains" ] } } } }, "responses": { "200": { "description": "Share domains removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Share link UUID \u2014 the id used by asset_share_* tools. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "url": { "type": "string", "nullable": true, "description": "The share URL to send recipients; re-readable, so it can be copied again any time. Null only for legacy shares minted before recoverable link storage \u2014 asset_share_rotate mints those a fresh one. e.g. 'https://sites.octave.app/s/eyJ...'" }, "access": { "type": "string", "enum": [ "allowlist", "anyone" ], "description": "The link's gate. 'allowlist' (the default) makes a viewer prove an allowlisted email \u2014 or a mailbox at an allowlisted domain \u2014 with a one-time code, and attributes the visit to them. 'anyone' means holding the link IS the credential: no check, and the visit is counted but attributed to nobody. e.g. 'allowlist'" }, "expiresAt": { "type": "string", "nullable": true, "description": "ISO-8601 expiry; null means it never expires. e.g. '2026-08-06T00:00:00.000Z'" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted exact recipient emails. e.g. ['sam@acme.com']" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted domains \u2014 any verified mailbox at these gets access. e.g. ['acme.com']" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-06T09:00:00.000Z'" } }, "required": [ "uuid", "url", "access", "expiresAt", "emails", "domains", "createdAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/access-requests/list": { "get": { "deprecated": false, "operationId": "listAccessRequests", "summary": "List Asset Access Requests", "description": "List access requests across ALL of the calling user's assets \u2014 the request inbox. Each entry is a code-verified person asking to view one of your assets; it embeds the target asset's uuid + identifier for follow-up Grant / Dismiss calls. Pending first, then most recently updated; filter with status 'pending' for the inbox / badge count.", "tags": [ "Asset" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "granted", "dismissed" ], "description": "Filter by request state; omit for all. Use 'pending' for the inbox / badge count. e.g. 'pending'" }, "required": false, "description": "Filter by request state; omit for all. Use 'pending' for the inbox / badge count. e.g. 'pending'", "name": "status", "in": "query" } ], "responses": { "200": { "description": "Asset access requests listed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Numeric id of the access request \u2014 pass it to asset_access_request_grant / asset_access_request_dismiss. e.g. 5" }, "email": { "type": "string", "description": "Requester's email, code-verified before the request was created. e.g. 'sam@acme.com'" }, "message": { "type": "string", "nullable": true, "description": "Optional note the requester attached; null when none. e.g. 'Need this for our vendor review'" }, "status": { "type": "string", "enum": [ "pending", "granted", "dismissed" ], "description": "Request state. One of: pending (awaiting a decision), granted (a share link was minted), dismissed ('not now' \u2014 a re-request returns it to pending). e.g. 'pending'" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-10T09:00:00.000Z'" }, "updatedAt": { "type": "string", "description": "ISO-8601 time of the last state change. e.g. '2026-07-11T14:30:00.000Z'" }, "artifact": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset the request targets \u2014 use it in grant/dismiss calls. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "identifier": { "type": "string", "description": "The asset's identifier/slug. e.g. 'q3-launch-microsite'" } }, "required": [ "uuid", "identifier" ], "description": "The asset this request targets." } }, "required": [ "id", "email", "message", "status", "createdAt", "updatedAt", "artifact" ] } }, "total": { "type": "number" } }, "required": [ "_metadata", "data", "total" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/access-requests/grant": { "post": { "deprecated": false, "operationId": "grantAccessRequest", "summary": "Grant Asset Access Request", "description": "Grant a pending access request: mints a fresh single-recipient, never-expiring share link for the requester's email and marks the request granted. NO email is sent \u2014 forward the returned share.url to the requester yourself (it also stays readable via List Asset Shares, so a lost link is recoverable). An already-granted request fails with 409. To take access back later, revoke the granted share with Revoke Asset Share.", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset the request targets \u2014 the artifact.uuid on an asset_access_requests_list entry. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "requestId": { "type": "integer", "description": "Numeric id of the access request, from asset_access_requests_list. e.g. 5" } }, "required": [ "uuid", "requestId" ] } } } }, "responses": { "200": { "description": "Asset access request granted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "number", "description": "Numeric id of the access request \u2014 pass it to asset_access_request_grant / asset_access_request_dismiss. e.g. 5" }, "email": { "type": "string", "description": "Requester's email, code-verified before the request was created. e.g. 'sam@acme.com'" }, "message": { "type": "string", "nullable": true, "description": "Optional note the requester attached; null when none. e.g. 'Need this for our vendor review'" }, "status": { "type": "string", "enum": [ "pending", "granted", "dismissed" ], "description": "Request state. One of: pending (awaiting a decision), granted (a share link was minted), dismissed ('not now' \u2014 a re-request returns it to pending). e.g. 'pending'" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-10T09:00:00.000Z'" }, "updatedAt": { "type": "string", "description": "ISO-8601 time of the last state change. e.g. '2026-07-11T14:30:00.000Z'" } }, "required": [ "id", "email", "message", "status", "createdAt", "updatedAt" ], "description": "The request, now status 'granted'." }, "share": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Share link UUID \u2014 the id used by asset_share_* tools. e.g. 'a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809'" }, "url": { "type": "string", "description": "The share URL embedding the link token. Always present here, and re-readable later via asset_shares_list. e.g. 'https://sites.octave.app/s/eyJ...'" }, "access": { "type": "string", "enum": [ "allowlist", "anyone" ], "description": "The link's gate. 'allowlist' (the default) makes a viewer prove an allowlisted email \u2014 or a mailbox at an allowlisted domain \u2014 with a one-time code, and attributes the visit to them. 'anyone' means holding the link IS the credential: no check, and the visit is counted but attributed to nobody. e.g. 'allowlist'" }, "expiresAt": { "type": "string", "nullable": true, "description": "ISO-8601 expiry; null means it never expires. e.g. '2026-08-06T00:00:00.000Z'" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted exact recipient emails. e.g. ['sam@acme.com']" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Allowlisted domains \u2014 any verified mailbox at these gets access. e.g. ['acme.com']" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-06T09:00:00.000Z'" } }, "required": [ "uuid", "url", "access", "expiresAt", "emails", "domains", "createdAt" ], "description": "The share link minted for the requester \u2014 single-recipient, never-expiring. Its url stays readable via asset_shares_list." } }, "required": [ "request", "share" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/access-requests/dismiss": { "post": { "deprecated": false, "operationId": "dismissAccessRequest", "summary": "Dismiss Asset Access Request", "description": "Dismiss a pending access request \u2014 'not now', not a block: if the requester verifies their email and asks again, the request returns to pending. Grants nothing and sends nothing. An already-granted request fails with 409 (dismissing wouldn't revoke access \u2014 revoke its share with Revoke Asset Share instead).", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "description": "UUID of the asset the request targets \u2014 the artifact.uuid on an asset_access_requests_list entry. e.g. '4f1e2a90-8b3d-4c21-9e07-2a1b3c4d5e6f'" }, "requestId": { "type": "integer", "description": "Numeric id of the access request, from asset_access_requests_list. e.g. 5" } }, "required": [ "uuid", "requestId" ] } } } }, "responses": { "200": { "description": "Asset access request dismissed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "number", "description": "Numeric id of the access request \u2014 pass it to asset_access_request_grant / asset_access_request_dismiss. e.g. 5" }, "email": { "type": "string", "description": "Requester's email, code-verified before the request was created. e.g. 'sam@acme.com'" }, "message": { "type": "string", "nullable": true, "description": "Optional note the requester attached; null when none. e.g. 'Need this for our vendor review'" }, "status": { "type": "string", "enum": [ "pending", "granted", "dismissed" ], "description": "Request state. One of: pending (awaiting a decision), granted (a share link was minted), dismissed ('not now' \u2014 a re-request returns it to pending). e.g. 'pending'" }, "createdAt": { "type": "string", "description": "ISO-8601 creation time. e.g. '2026-07-10T09:00:00.000Z'" }, "updatedAt": { "type": "string", "description": "ISO-8601 time of the last state change. e.g. '2026-07-11T14:30:00.000Z'" } }, "required": [ "id", "email", "message", "status", "createdAt", "updatedAt" ], "description": "The request, now status 'dismissed'." } }, "required": [ "request" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/access-token/generate": { "post": { "deprecated": false, "operationId": "generateAccessToken", "summary": "Generate Asset Access Token", "description": "Mint a per-user access token for the artifacts service, scoped to the calling user and workspace. The token authenticates direct calls to the artifacts service at the returned `apiBaseUrl` (`https://link.octavehq.com` in production \u2014 a public host; use the returned value, never a guessed hostname) \u2014 including asset creation/upload (multipart POST `{apiBaseUrl}/api/v1/artifacts/`), which has no /api/v2 proxy. Returns the plaintext token, which is shown ONLY here and on refresh \u2014 store it securely, it cannot be retrieved again. One token is active per user and workspace: calling again rotates it and invalidates the previous one, and other Octave surfaces acting as the same user (the in-app asset gallery, MCP tools) may rotate yours. Treat a 401 from the artifacts service as \"generate again and retry once\".", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Asset access token generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Plaintext per-user access token \u2014 returned ONLY here and on refresh; store it, it cannot be retrieved again. e.g. 'atk_7f3c9d2b8a...'" }, "prefix": { "type": "string", "description": "Short non-secret prefix identifying the token (safe to display/log). e.g. 'atk_7f3c'" }, "expiresAt": { "type": "string", "description": "ISO-8601 expiry, ~30 days out. e.g. '2026-08-02T09:00:00.000Z'" }, "apiBaseUrl": { "type": "string", "description": "PUBLIC origin of the artifacts service this token authorizes \u2014 direct uploads and artifact API calls go to `{apiBaseUrl}/api/v1/artifacts/...`. ALWAYS use this value; never guess or hardcode the artifacts hostname. e.g. 'https://link.octavehq.com'" } }, "required": [ "accessToken", "prefix", "expiresAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/asset/access-token/refresh": { "post": { "deprecated": false, "operationId": "refreshAccessToken", "summary": "Refresh Asset Access Token", "description": "Rotate the calling user's artifacts-service access token, invalidating the previous one. Returns the new plaintext token, which is shown ONLY here and on generate \u2014 store it securely, it cannot be retrieved again. Like generate, the response carries `apiBaseUrl` \u2014 the public artifacts-service origin the token authorizes; always use it over a guessed or cached hostname. Use this when the existing token is compromised or expired. One token is active per user and workspace, so rotation cuts off any other holder of the old token.", "tags": [ "Asset" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Asset access token refreshed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "accessToken": { "type": "string", "description": "Plaintext per-user access token \u2014 returned ONLY here and on refresh; store it, it cannot be retrieved again. e.g. 'atk_7f3c9d2b8a...'" }, "prefix": { "type": "string", "description": "Short non-secret prefix identifying the token (safe to display/log). e.g. 'atk_7f3c'" }, "expiresAt": { "type": "string", "description": "ISO-8601 expiry, ~30 days out. e.g. '2026-08-02T09:00:00.000Z'" }, "apiBaseUrl": { "type": "string", "description": "PUBLIC origin of the artifacts service this token authorizes \u2014 direct uploads and artifact API calls go to `{apiBaseUrl}/api/v1/artifacts/...`. ALWAYS use this value; never guess or hardcode the artifacts hostname. e.g. 'https://link.octavehq.com'" } }, "required": [ "accessToken", "prefix", "expiresAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "_metadata" ] } } } } } } }, "/api/v2/workflows/run": { "post": { "deprecated": false, "operationId": "runWorkflow", "summary": "Run a workflow", "description": "Runs a workflow asynchronously and returns a job OId to track execution.\n\nThe workflow's starting node (the node with no incoming edges) determines which agent runs first. Any additional fields in the request body beyond `workflowOId` and `callbackUrl` are forwarded as input to that starting node's agent.\n\nThe required input fields depend on the agent type configured on the workflow's starting node. Refer to the **Run Agent** (`/async/agent/run`) endpoint documentation for the input schema of each agent type.", "tags": [ "Workflow" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "workflowOId": { "type": "string", "minLength": 1, "description": "The OId of the workflow to run", "example": "caw_3rgkoHhR00cEdE9DjKeIK" }, "callbackUrl": { "type": "string", "format": "uri", "description": "Optional callback URL. If provided, results are POSTed to this URL on completion. If omitted, poll GET /workflows/run/status with the returned jobOId instead.", "example": "https://example.com/callback" } }, "required": [ "workflowOId" ], "additionalProperties": { "nullable": true }, "description": "Workflow execution input. Additional properties beyond workflowOId and callbackUrl are passed as input to the starting node's agent. See /async/agent/run for agent-specific input schemas." } } } }, "responses": { "200": { "description": "Workflow execution started successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobOId": { "type": "string", "description": "The OId of the job that was created to run the workflow", "example": "bsjob_3rgkoHhR00cEdE9DjKeIK" }, "message": { "type": "string", "description": "The message from the job", "example": "Workflow execution started successfully" } }, "required": [ "jobOId" ] } } } } } } }, "/api/v2/workflows/run/status": { "get": { "deprecated": false, "operationId": "getWorkflowRunStatus", "summary": "Get Workflow Run Status", "description": "Get the current status of a workflow run job. Use this to poll for completion after starting a workflow via POST /workflows/run. Recommended polling interval: 5\u201310 seconds.", "tags": [ "Workflow" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The OId of the workflow run job to check status for", "example": "bsjob_3rgkoHhR00cEdE9DjKeIK" }, "required": true, "description": "The OId of the workflow run job to check status for", "name": "jobOId", "in": "query" } ], "responses": { "200": { "description": "Workflow run status", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "jobOId": { "type": "string", "description": "The OId of the job" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "PAUSED", "COMPLETED", "FAILED", "CANCELLED" ], "description": "Current job status: PENDING, RUNNING, PAUSED, COMPLETED, FAILED, or CANCELLED" }, "totalCount": { "type": "number", "description": "Total number of items to process" }, "processedCount": { "type": "number", "description": "Number of items processed so far" }, "successCount": { "type": "number", "description": "Number of items that succeeded" }, "failedCount": { "type": "number", "description": "Number of items that failed" }, "startedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the job started processing" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the job reached a terminal state" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the job was created" }, "workflowOId": { "type": "string", "nullable": true, "description": "The OId of the workflow that was executed" }, "callbackUrl": { "type": "string", "nullable": true, "description": "The callback URL if one was provided" }, "circuitBreakerReason": { "type": "string", "nullable": true, "description": "Reason for circuit breaker pause, if applicable" } }, "required": [ "jobOId", "status", "totalCount", "processedCount", "successCount", "failedCount", "startedAt", "completedAt", "createdAt", "workflowOId" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/async/agent/run/status": { "get": { "deprecated": false, "operationId": "getAsyncAgentRunStatus", "summary": "Get Async Agent Run Status", "description": "Get the current status and result of an async agent run. Use this to poll for completion after starting an agent run via POST /async/agent/run. Recommended polling interval: 5\u201310 seconds.", "tags": [ "Async" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The request ID returned by the async agent run POST endpoint", "example": "asyncReqID_3rgkoHhR00cEdE9DjKeIK" }, "required": true, "description": "The request ID returned by the async agent run POST endpoint", "name": "requestId", "in": "query" } ], "responses": { "200": { "description": "Async agent run status", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The request ID" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ], "description": "Current request status: pending, completed, or failed" }, "result": { "nullable": true, "description": "The processed result data, available when status is completed" }, "error": { "type": "string", "nullable": true, "description": "Error message if the request failed" }, "createdAt": { "type": "string", "nullable": true, "description": "When the request was created (ISO 8601)" } }, "required": [ "requestId", "status" ] } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Request not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/motion/list": { "get": { "deprecated": false, "operationId": "listMotions", "summary": "List motions", "description": "List motions for the workspace, optionally filtered by offering", "tags": [ "Motion" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Filter by offering oId (product or service)" }, "required": false, "description": "Filter by offering oId (product or service)", "name": "offeringOId", "in": "query" }, { "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 20, "example": 20, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "default": 0, "example": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Motion list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "description": "Whether there are more results" }, "total": { "type": "number", "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MotionListItem" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } } } } }, "/api/v2/motion/get": { "get": { "deprecated": false, "operationId": "getMotion", "summary": "Get a motion", "description": "Fetch a single motion by oId", "tags": [ "Motion" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Motion oId", "example": "mot_abc123" }, "required": true, "description": "Motion oId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Motion data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Motion" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/motion/create": { "post": { "deprecated": false, "operationId": "createMotion", "summary": "Create a motion", "description": "Create a new motion with a default playbook. The offering must pass motion eligibility (status ELIGIBLE). Returns 400 when status is INELIGIBLE or LIBRARY_ADJUSTMENT_REQUIRED.", "tags": [ "Motion" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Motion name" }, "description": { "type": "string", "description": "Motion description" }, "offeringId": { "type": "string", "description": "Offering oId (product or service)" }, "motionType": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ], "description": "Motion type" }, "data": { "type": "object", "properties": { "overview": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [] }, "scope": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [] }, "additionalContext": { "type": "string", "default": "" }, "attachedSources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" }, "displayValue": { "type": "string" } }, "required": [ "type", "value" ] }, "default": [] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } }, "guidingNotes": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Motion configuration data" }, "srcOfferingId": { "type": "string", "description": "Optional source/FROM offering oId (cross-sell, convert-free-to-paid)." }, "competitorOId": { "type": "string", "description": "Optional competitor oId being displaced (displace-incumbent)." }, "coreFeatureOIds": { "type": "array", "items": { "type": "string" }, "description": "Optional core-feature oIds to emphasize." } }, "required": [ "name", "offeringId", "motionType", "data" ] } } } }, "responses": { "200": { "description": "Created motion", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Motion" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Offering not eligible for motion creation (library matrix blockers or adjustment required)", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/motion/update": { "post": { "deprecated": false, "operationId": "updateMotion", "summary": "Update a motion", "description": "Update fields on an existing motion", "tags": [ "Motion" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "Motion oId to update" }, "name": { "type": "string", "description": "New name" }, "description": { "type": "string", "description": "New description" }, "offeringId": { "type": "string", "description": "New offering oId" }, "motionType": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ], "description": "New motion type" }, "data": { "type": "object", "properties": { "overview": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [] }, "scope": { "type": "array", "nullable": true, "items": { "type": "string" }, "default": [] }, "additionalContext": { "type": "string", "default": "" }, "attachedSources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "value": { "type": "string" }, "displayValue": { "type": "string" } }, "required": [ "type", "value" ] }, "default": [] }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } }, "guidingNotes": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "Updated motion data" } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Updated motion", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/Motion" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/motion/delete": { "delete": { "deprecated": false, "operationId": "deleteMotion", "summary": "Delete a motion", "description": "Soft-delete a motion and all its ICP cells and learnings", "tags": [ "Motion" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Motion oId to delete" }, "required": true, "description": "Motion oId to delete", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deletion result", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "success": { "type": "boolean", "description": "Whether the deletion succeeded" } }, "required": [ "_metadata", "success" ] } } } } } } }, "/api/v2/motion-playbook/list": { "get": { "deprecated": false, "operationId": "listMotionPlaybooks", "summary": "List motion playbooks", "description": "List motion playbooks, optionally filtered by motion, offering, or motion type", "tags": [ "MotionPlaybook" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "nullable": true, "description": "Filter by motion oId" }, "required": false, "description": "Filter by motion oId", "name": "motionOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "description": "Filter by offering oId" }, "required": false, "description": "Filter by offering oId", "name": "offeringOId", "in": "query" }, { "schema": { "type": "string", "nullable": true, "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT", null ], "description": "Filter by motion type" }, "required": false, "description": "Filter by motion type", "name": "motionType", "in": "query" }, { "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 20, "example": 20, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "default": 0, "example": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Motion playbook list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "hasNext": { "type": "boolean", "description": "Whether there are more results" }, "total": { "type": "number", "description": "Total number of results" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MotionPlaybookListItem" } } }, "required": [ "_metadata", "hasNext", "total", "data" ] } } } } } } }, "/api/v2/motion-playbook/get": { "get": { "deprecated": false, "operationId": "getMotionPlaybook", "summary": "Get a motion playbook", "description": "Fetch a single motion playbook by oId", "tags": [ "MotionPlaybook" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Motion playbook oId", "example": "pb_abc123" }, "required": true, "description": "Motion playbook oId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Motion playbook data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/MotionPlaybook" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/motion-playbook/create": { "post": { "deprecated": false, "operationId": "createMotionPlaybook", "summary": "Create a motion playbook", "description": "Create a new playbook for an existing motion", "tags": [ "MotionPlaybook" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "motionType": { "type": "string", "enum": [ "NET_NEW", "UPSELL", "CROSS_SELL", "CONVERT_FREE_TO_PAID", "RENEW_AND_RETAIN", "DISPLACE_INCUMBENT" ] }, "offeringOId": { "type": "string" }, "narrativeType": { "type": "string", "enum": [ "THEMATIC", "MILESTONE", "ACCOUNT", "COMPETITIVE", "GEO", "CUSTOM" ] }, "narrativeInput": { "type": "string" }, "competitorOIds": { "type": "array", "items": { "type": "string" }, "default": [] }, "accountDomain": { "type": "string", "nullable": true }, "buyingTriggerOId": { "type": "string", "nullable": true }, "scope": { "type": "object", "properties": { "icpScopeMode": { "type": "string", "enum": [ "AUTO", "MANUAL" ] }, "allSegments": { "type": "boolean" }, "segmentOIds": { "type": "array", "items": { "type": "string" } }, "allPersonas": { "type": "boolean" }, "personaOIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "icpScopeMode", "allSegments", "segmentOIds", "allPersonas", "personaOIds" ] }, "anchorOverrides": { "type": "object", "properties": { "useCases": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "oIds" ] }, "references": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "oIds" ] }, "proofPoints": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "oIds" ] }, "alternatives": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "default": { "mode": "AUTO", "oIds": [] }, "required": [ "mode", "oIds" ] }, "buyingTriggers": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "default": { "mode": "AUTO", "oIds": [] }, "required": [ "mode", "oIds" ] }, "coreFeatures": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "default": { "mode": "AUTO", "oIds": [] }, "required": [ "mode", "oIds" ] }, "objections": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "AUTO", "MANUAL", "OFF" ] }, "oIds": { "type": "array", "items": { "type": "string" } } }, "default": { "mode": "AUTO", "oIds": [] }, "required": [ "mode", "oIds" ] } }, "required": [ "useCases", "references", "proofPoints" ] }, "additionalContext": { "type": "string", "nullable": true }, "additionalContextSources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "GOOGLE_DRIVE_FILE_ID", "GENERATIVE_NAME", "OID", "COMPANY_NAME", "FIELDWISE_DOCUMENT_ID", "RAG_DOCUMENT_ID", "RESOURCE", "REPORT", "REPORT_SECTION", "EVENT_OID_FINDINGS", "FINDING_OIDS" ] }, "value": { "type": "string" }, "name": { "type": "string", "nullable": true }, "details": { "type": "string", "nullable": true }, "useNameIfUrlFails": { "type": "boolean", "nullable": true } }, "required": [ "type", "value" ] }, "default": [] }, "brandVoiceOId": { "type": "string", "nullable": true }, "additionalProperties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "number" }, { "type": "boolean" } ] } }, "enableLearnings": { "type": "boolean", "default": true } }, "required": [ "name", "motionType", "offeringOId", "narrativeType", "narrativeInput", "scope", "anchorOverrides" ] } } } }, "responses": { "200": { "description": "Created motion playbook", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/MotionPlaybook" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/motion-playbook/update": { "post": { "deprecated": false, "operationId": "updateMotionPlaybook", "summary": "Update a motion playbook", "description": "Update name, active state, or narrative sections of a motion playbook", "tags": [ "MotionPlaybook" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "Motion playbook oId to update" }, "name": { "type": "string", "minLength": 1, "description": "New playbook name" }, "active": { "type": "boolean", "description": "Set active state" }, "motionFraming": { "type": "string", "nullable": true, "description": "Updated motion framing narrative" }, "keyMessaging": { "type": "array", "items": { "type": "string" }, "description": "Updated key messaging points" }, "keyPositioning": { "type": "array", "items": { "type": "string" }, "description": "Updated key positioning points" } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "Updated motion playbook", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/MotionPlaybook" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/motion-playbook/delete": { "delete": { "deprecated": false, "operationId": "deleteMotionPlaybook", "summary": "Delete a motion playbook", "description": "Soft-delete a motion playbook", "tags": [ "MotionPlaybook" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Motion playbook oId to delete" }, "required": true, "description": "Motion playbook oId to delete", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Deletion result", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "success": { "type": "boolean", "description": "Whether the deletion succeeded" } }, "required": [ "_metadata", "success" ] } } } } } } }, "/api/v2/motion-icp/list": { "get": { "deprecated": false, "operationId": "listMotionIcps", "summary": "List Motion ICP cells", "description": "List all ICP cells for a motion, optionally filtered to a specific playbook. Returns persona, segment, and status for each cell. Use the returned oId with /motion-icp/get to retrieve full details and recommendations.", "tags": [ "MotionICP" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Motion oId (mot_ prefix). Required." }, "required": true, "description": "Motion oId (mot_ prefix). Required.", "name": "motionOId", "in": "query" }, { "schema": { "type": "string", "description": "Filter to a specific motion playbook oId (mpb_ prefix). Omit to return all playbooks." }, "required": false, "description": "Filter to a specific motion playbook oId (mpb_ prefix). Omit to return all playbooks.", "name": "motionPlaybookOId", "in": "query" } ], "responses": { "200": { "description": "ICP matrix rows for the motion", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MotionIcpListItem" } }, "total": { "type": "integer" } }, "required": [ "data", "total" ] } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/motion-icp/get": { "get": { "deprecated": false, "operationId": "getMotionIcp", "summary": "Get Motion ICP detail", "description": "Get full detail for a Motion ICP cell including the AI-generated narrative and learning count. Use includeReport=true to include the latest report run summary and comparisonWithPrevious. Use GET /api/v2/motion-icp/elements/list to fetch recommended library entities for this cell.", "tags": [ "MotionICP" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Motion ICP oId (micp_ prefix)" }, "required": true, "description": "Motion ICP oId (micp_ prefix)", "name": "oId", "in": "query" }, { "schema": { "type": "string", "description": "Pass true to include the latest completed report run summary and comparisonWithPrevious in the response. Defaults to false." }, "required": false, "description": "Pass true to include the latest completed report run summary and comparisonWithPrevious in the response. Defaults to false.", "name": "includeReport", "in": "query" } ], "responses": { "200": { "description": "Motion ICP detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/MotionIcpDetail" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/motion-icp/elements/list": { "get": { "deprecated": false, "operationId": "listMotionIcpElements", "summary": "List recommended elements for a Motion ICP", "description": "Returns the recommended library entities (use cases, proof points, reference customers, competitors, alternatives, buying triggers, objections) linked to a specific Motion ICP cell from its active version.", "tags": [ "MotionICP" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Motion ICP oId (micp_ prefix). Obtain from the motion ICP matrix or find_motion_icp MCP tool." }, "required": true, "description": "Motion ICP oId (micp_ prefix). Obtain from the motion ICP matrix or find_motion_icp MCP tool.", "name": "motionIcpOId", "in": "query" } ], "responses": { "200": { "description": "Recommended elements list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MotionIcpElement" } }, "total": { "type": "integer", "description": "Total recommended elements for this ICP" } }, "required": [ "_metadata", "data", "total" ] } } } } } } }, "/api/v2/motion-icp/learnings/list": { "get": { "deprecated": false, "operationId": "listMotionIcpLearnings", "summary": "List learnings for a Motion ICP", "description": "Returns the current learnings for a specific Motion ICP cell, sorted by pinned status and confidence.", "tags": [ "MotionICP" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Motion ICP oId (micp_*). Obtain this from the find_motion_icp MCP tool or the motion ICP matrix." }, "required": true, "description": "Motion ICP oId (micp_*). Obtain this from the find_motion_icp MCP tool or the motion ICP matrix.", "name": "motionIcpOId", "in": "query" } ], "responses": { "200": { "description": "Learnings list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MotionIcpLearning" } }, "total": { "type": "number", "description": "Total learnings for this ICP" } }, "required": [ "_metadata", "data", "total" ] } } } } } } }, "/api/v2/motion-icp/learnings/get": { "get": { "deprecated": false, "operationId": "getMotionIcpLearning", "summary": "Get a Motion ICP learning", "description": "Fetch a single learning by oId", "tags": [ "MotionICP" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Learning oId (lea_*)", "example": "lea_abc123" }, "required": true, "description": "Learning oId (lea_*)", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Learning detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/MotionIcpLearning" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/report-group/list": { "get": { "deprecated": false, "operationId": "listReportGroups", "summary": "List report groups", "description": "List GTM report groups (Beats), including scheduling status and config count", "tags": [ "ReportGroup" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 50, "example": 50, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "default": 0, "example": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Report group list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportGroup" } }, "total": { "type": "number", "description": "Total matching groups" }, "hasNext": { "type": "boolean", "description": "Whether more results exist" } }, "required": [ "_metadata", "data", "total", "hasNext" ] } } } } } } }, "/api/v2/report-group/get": { "get": { "deprecated": false, "operationId": "getReportGroup", "summary": "Get a report group", "description": "Get a single report group (Beats schedule) by oId, including its report configs", "tags": [ "ReportGroup" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Report group oId", "example": "rcg_abc123" }, "required": true, "description": "Report group oId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Report group", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/ReportGroupDetail" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/report-config/list": { "get": { "deprecated": false, "operationId": "listReportConfigs", "summary": "List report configs", "description": "List report configurations, optionally filtered by group", "tags": [ "ReportConfig" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Filter by report group oId" }, "required": false, "description": "Filter by report group oId", "name": "groupOId", "in": "query" } ], "responses": { "200": { "description": "Report config list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportConfig" } }, "total": { "type": "number", "description": "Total configs returned" } }, "required": [ "_metadata", "data", "total" ] } } } } } } }, "/api/v2/report-config/get": { "get": { "deprecated": false, "operationId": "getReportConfig", "summary": "Get a report config", "description": "Get a single report configuration by oId", "tags": [ "ReportConfig" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Report config oId", "example": "rc_abc123" }, "required": true, "description": "Report config oId", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Report config", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/ReportConfig" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/report-run/list": { "get": { "deprecated": false, "operationId": "listReportRuns", "summary": "List report runs", "description": "List report runs for a given report config, ordered by most recent first", "tags": [ "ReportRun" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Filter runs by report config oId (rc_ prefix)" }, "required": true, "description": "Filter runs by report config oId (rc_ prefix)", "name": "configOId", "in": "query" }, { "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "default": 20, "example": 20, "description": "Limit" }, "required": false, "description": "Limit", "name": "limit", "in": "query" }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "default": 0, "example": 0, "description": "Offset" }, "required": false, "description": "Offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Report run list", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReportRunSummary" } }, "total": { "type": "number", "description": "Total runs returned" } }, "required": [ "_metadata", "data", "total" ] } } } } } } }, "/api/v2/report-run/get": { "get": { "deprecated": false, "operationId": "getReportRun", "summary": "Get a report run", "description": "Get a single report run with full section details and narrative analysis", "tags": [ "ReportRun" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "Report run oId (rr_ prefix)", "example": "rr_abc123" }, "required": true, "description": "Report run oId (rr_ prefix)", "name": "oId", "in": "query" } ], "responses": { "200": { "description": "Report run detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/ReportRunDetail" } }, "required": [ "_metadata", "data" ] } } } } } } }, "/api/v2/insights/workspace-baseline": { "get": { "operationId": "getWorkspaceBaseline", "summary": "Workspace Baseline", "tags": [ "Insights" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "format": "date-time", "description": "Anchor ISO datetime. Defaults to now." }, "required": false, "description": "Anchor ISO datetime. Defaults to now.", "name": "anchorAt", "in": "query" } ], "responses": { "200": { "description": "Workspace outcome baseline for the current period windows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "anchorAt": { "type": "string" }, "week": { "$ref": "#/components/schemas/WorkspaceBaseline" }, "month": { "$ref": "#/components/schemas/WorkspaceBaseline" }, "quarter": { "$ref": "#/components/schemas/WorkspaceBaseline" } }, "required": [ "anchorAt", "week", "month", "quarter" ] } }, "required": [ "data" ] } } } } } } }, "/api/v2/insights/entity-stats": { "get": { "operationId": "getEntityStats", "summary": "Entity Stats", "tags": [ "Insights" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "enum": [ "persona", "product", "service", "solution", "use_case", "playbook", "proof_point", "competitor", "alternative", "buying_trigger", "core_feature", "objection", "reference", "hypothesis", "segment", "target_icp", "motion_icp" ], "description": "Type of entity to query stats for" }, "required": true, "description": "Type of entity to query stats for", "name": "entityType", "in": "query" }, { "schema": { "type": "string", "description": "The oId of the entity" }, "required": true, "description": "The oId of the entity", "name": "entityOId", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Anchor ISO datetime for period resolution. Defaults to now." }, "required": false, "description": "Anchor ISO datetime for period resolution. Defaults to now.", "name": "anchorAt", "in": "query" } ], "responses": { "200": { "description": "Win rate and lift stats for a single entity across period windows", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "anchorAt": { "type": "string" }, "week": { "$ref": "#/components/schemas/EntityStats" }, "month": { "$ref": "#/components/schemas/EntityStats" }, "quarter": { "$ref": "#/components/schemas/EntityStats" } }, "required": [ "anchorAt", "week", "month", "quarter" ] } }, "required": [ "data" ] } } } } } } }, "/api/v2/insights/entity-time-series": { "get": { "operationId": "getEntityTimeSeries", "summary": "Entity Time Series", "tags": [ "Insights" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "enum": [ "persona", "product", "service", "solution", "use_case", "playbook", "proof_point", "competitor", "alternative", "buying_trigger", "core_feature", "objection", "reference", "hypothesis", "segment", "target_icp", "motion_icp" ], "description": "Type of entity" }, "required": true, "description": "Type of entity", "name": "entityType", "in": "query" }, { "schema": { "type": "string", "description": "The oId of the entity" }, "required": true, "description": "The oId of the entity", "name": "entityOId", "in": "query" }, { "schema": { "type": "string", "enum": [ "week", "month", "quarter" ], "description": "Period granularity filter (week/month/quarter)" }, "required": false, "description": "Period granularity filter (week/month/quarter)", "name": "periodType", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 52, "default": 12, "description": "Number of periods to return (max 52)" }, "required": false, "description": "Number of periods to return (max 52)", "name": "periodCount", "in": "query" } ], "responses": { "200": { "description": "Time-series of stats rows for a single entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityStats" } } }, "required": [ "data" ] } } } } } } }, "/api/v2/insights/entity-usage": { "get": { "operationId": "getEntityUsage", "summary": "Entity Usage", "description": "A library entity's activity record: mention and conversation counts, the per-channel split, first/last mention, days since last mention, a daily series, whether mentions are rising or falling, and the window's deal outcomes (presence, win rate, lift) when the workspace has analytics. Use `insights/entity-stats` instead for per-period buckets. Accepts any library entity oId \u2014 the type is derived from its prefix. Entity types with no conversation surface (brand voices, skills) return 400 rather than an empty report.", "tags": [ "Insights" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "The oId of any library entity. The type is derived from the oId prefix (pe_ persona, px_ product, sg_ segment, uu_ use case, cp_ competitor, \u2026)." }, "required": true, "description": "The oId of any library entity. The type is derived from the oId prefix (pe_ persona, px_ product, sg_ segment, uu_ use case, cp_ competitor, \u2026).", "name": "entityOId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90, "description": "Lookback window in days. Scopes the mention/conversation counts, the channel split, the daily series and the trend comparison. First/last mention stay all-time." }, "required": false, "description": "Lookback window in days. Scopes the mention/conversation counts, the channel split, the daily series and the trend comparison. First/last mention stay all-time.", "name": "days", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Inclusive YYYY-MM-DD start of an explicit window scoping the aggregate counts, overriding `days` for those counts only. Must be sent together with `end`. First/last mention stay all-time and the daily series stays the full `days` window \u2014 so with a range narrower than `days`, the counts and the trend cover different spans." }, "required": false, "description": "Inclusive YYYY-MM-DD start of an explicit window scoping the aggregate counts, overriding `days` for those counts only. Must be sent together with `end`. First/last mention stay all-time and the daily series stays the full `days` window \u2014 so with a range narrower than `days`, the counts and the trend cover different spans.", "name": "start", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Inclusive YYYY-MM-DD end of the aggregate window." }, "required": false, "description": "Inclusive YYYY-MM-DD end of the aggregate window.", "name": "end", "in": "query" } ], "responses": { "200": { "description": "Finding-activity usage for a single library entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "entityOId": { "type": "string" }, "entityType": { "type": "string", "enum": [ "offering", "persona", "useCase", "competitor", "alternative", "buyingTrigger", "coreFeature", "objection", "segment", "proofPoint", "reference", "playbook" ], "description": "The usage surface the counts are attributed to. Products, services and solutions all report as `offering` \u2014 they share one finding pivot." }, "usage": { "type": "object", "properties": { "totalFindings": { "type": "number" }, "totalEvents": { "type": "number" }, "findingsByChannel": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string" }, "count": { "type": "number" }, "eventCount": { "type": "number" } }, "required": [ "channel", "count", "eventCount" ] } }, "firstMentioned": { "type": "string", "nullable": true }, "lastMentioned": { "type": "string", "nullable": true }, "daysSinceLastMentioned": { "type": "number", "nullable": true }, "trend": { "type": "object", "properties": { "recentFindings": { "type": "number" }, "priorFindings": { "type": "number" }, "halfWindowDays": { "type": "number" }, "direction": { "type": "string", "enum": [ "rising", "falling", "steady", "no_activity" ] } }, "required": [ "recentFindings", "priorFindings", "halfWindowDays", "direction" ] }, "windowDays": { "type": "number" }, "dealOutcomes": { "type": "object", "properties": { "dealsWon": { "type": "object", "properties": { "withEntity": { "type": "number" }, "workspaceTotal": { "type": "number" }, "share": { "type": "number", "nullable": true } }, "required": [ "withEntity", "workspaceTotal", "share" ] }, "dealsLost": { "type": "object", "properties": { "withEntity": { "type": "number" }, "workspaceTotal": { "type": "number" }, "share": { "type": "number", "nullable": true } }, "required": [ "withEntity", "workspaceTotal", "share" ] }, "dealsOpen": { "type": "object", "properties": { "withEntity": { "type": "number" }, "workspaceTotal": { "type": "number" }, "share": { "type": "number", "nullable": true } }, "required": [ "withEntity", "workspaceTotal", "share" ] }, "presenceRate": { "type": "number", "nullable": true }, "winRate": { "type": "number", "nullable": true }, "winRateWithoutEntity": { "type": "number", "nullable": true }, "liftScore": { "type": "number", "nullable": true }, "wonAmount": { "type": "number" }, "sentiment": { "type": "object", "nullable": true, "properties": { "positive": { "type": "number" }, "neutral": { "type": "number" }, "negative": { "type": "number" }, "unknown": { "type": "number" } }, "required": [ "positive", "neutral", "negative", "unknown" ] } }, "required": [ "dealsWon", "dealsLost", "dealsOpen", "presenceRate", "winRate", "winRateWithoutEntity", "liftScore", "wonAmount", "sentiment" ] }, "dailyCounts": { "type": "array", "items": { "type": "number" } }, "dailyCountsStartDate": { "type": "string" } }, "required": [ "totalFindings", "totalEvents", "findingsByChannel", "firstMentioned", "lastMentioned", "daysSinceLastMentioned", "trend", "windowDays", "dailyCounts", "dailyCountsStartDate" ] } }, "required": [ "entityOId", "entityType", "usage" ] } }, "required": [ "data" ] } } } }, "400": { "description": "Malformed oId, an entity type with no usage surface, or `start`/`end` sent alone", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "No entity with that oId exists in this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/insights/top-entities": { "get": { "operationId": "getTopEntities", "summary": "Top Entities", "tags": [ "Insights" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "enum": [ "week", "month", "quarter" ], "description": "Period granularity" }, "required": true, "description": "Period granularity", "name": "periodType", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Start of the period window (ISO datetime)" }, "required": true, "description": "Start of the period window (ISO datetime)", "name": "periodStart", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10, "description": "Max number of results to return" }, "required": false, "description": "Max number of results to return", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "desc = highest lift first (what's working); asc = lowest lift first" }, "required": false, "description": "desc = highest lift first (what's working); asc = lowest lift first", "name": "sort", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "persona", "product", "service", "solution", "use_case", "playbook", "proof_point", "competitor", "alternative", "buying_trigger", "core_feature", "objection", "reference", "hypothesis", "segment", "target_icp", "motion_icp" ] }, "description": "Filter to specific entity types. Omit for all types." }, "required": false, "description": "Filter to specific entity types. Omit for all types.", "name": "entityTypes", "in": "query" } ], "responses": { "200": { "description": "Top (or bottom) entities ranked by lift score", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityStatsWithName" } } }, "required": [ "data" ] } } } } } } }, "/api/v2/insights/competitive": { "get": { "operationId": "getCompetitiveLandscape", "summary": "Competitive Landscape", "tags": [ "Insights" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "enum": [ "week", "month", "quarter" ], "description": "Period granularity" }, "required": true, "description": "Period granularity", "name": "periodType", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Start of the period window (ISO datetime)" }, "required": true, "description": "Start of the period window (ISO datetime)", "name": "periodStart", "in": "query" } ], "responses": { "200": { "description": "Competitor and alternative entity stats, sorted by win rate impact", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityStatsWithName" } } }, "required": [ "data" ] } } } } } } }, "/api/v2/insights/library-health": { "get": { "operationId": "getLibraryHealth", "summary": "Library Health", "tags": [ "Insights" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "enum": [ "week", "month", "quarter" ], "description": "Period granularity" }, "required": true, "description": "Period granularity", "name": "periodType", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Start of the period window (ISO datetime)" }, "required": true, "description": "Start of the period window (ISO datetime)", "name": "periodStart", "in": "query" } ], "responses": { "200": { "description": "Per-entity-type health summary (findings, deal counts) for the heatmap", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LibraryHealthRow" } } }, "required": [ "data" ] } } } } } } }, "/api/v2/event/list": { "get": { "operationId": "listEvents", "summary": "List Events", "tags": [ "Events" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "format": "date-time", "description": "Start of the time range (ISO 8601 datetime)" }, "required": true, "description": "Start of the time range (ISO 8601 datetime)", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "End of the time range (ISO 8601 datetime). Defaults to now." }, "required": false, "description": "End of the time range (ISO 8601 datetime). Defaults to now.", "name": "endDate", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "maximum": 100, "default": 20, "description": "Maximum number of events to return (max 100)" }, "required": false, "description": "Maximum number of events to return (max 100)", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "default": 0, "description": "Number of events to skip for pagination" }, "required": false, "description": "Number of events to skip for pagination", "name": "offset", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL_SENT", "EMAIL_REPLY_RECEIVED", "CALL_TRANSCRIPT", "DEAL_WON", "DEAL_LOST", "OPPORTUNITY_CREATED", "MEETING_BOOKED", "RESOURCE_INDEXED", "RESOURCE_REINDEXED", "PROJECT_UPDATE", "TASK_COMPLETED", "ENTITY_CREATED", "ENTITY_UPDATED", "SOCIAL_MESSAGE_SENT", "SOCIAL_MESSAGE_RECEIVED", "SOCIAL_CONNECTION_SENT", "SOCIAL_CONNECTION_ACCEPTED", "AD_SET_PUBLISHED", "AD_PERFORMANCE_SNAPSHOT", "BULK_IMPORT_SUMMARY", "PROCESSING_NOT_APPLICABLE", "PROVIDER_EVENT_TYPE_UNKNOWN", "UNKNOWN" ] }, "description": "Filter by event types" }, "required": false, "description": "Filter by event types", "name": "eventTypes", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "EMAIL", "CALL", "CRM", "RESOURCE", "REVISION", "SOCIAL", "ADS", "PRODUCT", "UNKNOWN" ] }, "description": "Filter by event categories" }, "required": false, "description": "Filter by event categories", "name": "eventCategories", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "DISCOVERY", "DEMO", "TECHNICAL_EVALUATION", "WORKING_SESSION", "NEGOTIATION_PRICING", "ONBOARDING", "CHECK_IN_SUCCESS", "QBR_RENEWAL", "EXPANSION_UPSELL", "ESCALATION_CHURN_RISK", "SUPPORT", "INTERNAL_SYNC", "OTHER" ] }, "description": "Filter calls by classified purpose (single value, repeated param, or comma-separated)" }, "required": false, "description": "Filter calls by classified purpose (single value, repeated param, or comma-separated)", "name": "callPurposes", "in": "query" } ], "responses": { "200": { "description": "List of events for the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "EMAIL_SENT", "EMAIL_REPLY_RECEIVED", "CALL_TRANSCRIPT", "DEAL_WON", "DEAL_LOST", "OPPORTUNITY_CREATED", "MEETING_BOOKED", "RESOURCE_INDEXED", "RESOURCE_REINDEXED", "PROJECT_UPDATE", "TASK_COMPLETED", "ENTITY_CREATED", "ENTITY_UPDATED", "SOCIAL_MESSAGE_SENT", "SOCIAL_MESSAGE_RECEIVED", "SOCIAL_CONNECTION_SENT", "SOCIAL_CONNECTION_ACCEPTED", "AD_SET_PUBLISHED", "AD_PERFORMANCE_SNAPSHOT", "BULK_IMPORT_SUMMARY", "PROCESSING_NOT_APPLICABLE", "PROVIDER_EVENT_TYPE_UNKNOWN", "UNKNOWN" ] }, "eventTimestamp": { "type": "string", "nullable": true, "format": "date-time" }, "processingStatus": { "type": "string" }, "providerName": { "type": "string" }, "eventSummary": { "type": "string" }, "callPurpose": { "type": "string", "enum": [ "DISCOVERY", "DEMO", "TECHNICAL_EVALUATION", "WORKING_SESSION", "NEGOTIATION_PRICING", "ONBOARDING", "CHECK_IN_SUCCESS", "QBR_RENEWAL", "EXPANSION_UPSELL", "ESCALATION_CHURN_RISK", "SUPPORT", "INTERNAL_SYNC", "OTHER" ], "description": "Classified purpose of the call (CALL_TRANSCRIPT only)" } }, "required": [ "oId", "eventType", "eventTimestamp" ] } }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "events", "total", "hasMore" ] } }, "required": [ "data" ] } } } } } } }, "/api/v2/event/import": { "post": { "deprecated": false, "operationId": "importEvents", "summary": "Bulk import events", "description": "Imports a batch of events (calls, emails, CRM, social) into the analytics pipeline. Accepts up to 1000 events per request; events are ingested asynchronously.\n\nOne import job is created per event type present in the request; each job is tracked independently via GET /event/import/status.\n\n**Deduplication**: supply `eventId` on each event for predictable dedupe, otherwise a deterministic ID is derived from the event's content. Events whose ID matches an existing event in the workspace are skipped (reported as `preSkipped`); duplicate IDs within one request keep the first occurrence (later indices reported in `duplicatesInBatch`).\n\n**Skipped vs failed**: only processable event types produce analytics events (email `sent`/`reply`, call `transcript`, all CRM types, all social types) \u2014 other event types are accepted but land in the job's `skipped` count, alongside duplicates and internal-only events. `ingested` is the authoritative success count.\n\n**Callback**: if `callbackUrl` is provided, each job POSTs its final counts to that URL once on completion (one callback per job; delivery is best-effort \u2014 poll the status endpoint as the source of truth).", "tags": [ "Events" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "eventTimestamp": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "string", "format": "date-time" } ] }, "eventType": { "type": "string", "enum": [ "sent", "reply", "opened", "clicked", "bounced", "unsubscribed" ] }, "subject": { "type": "string" }, "body": { "type": "object", "properties": { "text": { "type": "string" }, "html": { "type": "string" } } }, "from": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "email" ] }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "email" ] }, "minItems": 1 }, "cc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "email" ] } }, "bcc": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "email" ] } }, "eventId": { "type": "string", "maxLength": 255 }, "conversationId": { "type": "string" }, "campaignId": { "type": "string" }, "octaveRequestId": { "type": "string" }, "crmOpportunityId": { "type": "string" }, "crmAccountId": { "type": "string" }, "crmAccountDomain": { "type": "string" }, "sourceProviderName": { "type": "string" }, "customMetadata": { "type": "object", "additionalProperties": { "nullable": true } }, "type": { "type": "string", "enum": [ "email" ] } }, "required": [ "eventTimestamp", "eventType", "subject", "body", "from", "to", "type" ] }, { "type": "object", "properties": { "eventTimestamp": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "string", "format": "date-time" } ] }, "eventType": { "type": "string", "enum": [ "transcript", "scheduled", "completed", "missed" ] }, "title": { "type": "string" }, "transcript": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "type": "object", "properties": { "speaker": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "internal", "external" ] } }, "required": [ "name" ] }, "text": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "speaker", "text" ] }, "minItems": 1 } ] }, "participants": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "internal", "external" ] } }, "required": [ "name" ] }, "minItems": 1 }, "duration": { "type": "number" }, "recordingUrl": { "type": "string", "format": "uri" }, "meetingPlatform": { "type": "string" }, "eventId": { "type": "string", "maxLength": 255 }, "conversationId": { "type": "string" }, "crmOpportunityId": { "type": "string" }, "crmAccountId": { "type": "string" }, "crmAccountDomain": { "type": "string" }, "sourceProviderName": { "type": "string" }, "customMetadata": { "type": "object", "additionalProperties": { "nullable": true } }, "type": { "type": "string", "enum": [ "call" ] } }, "required": [ "eventTimestamp", "eventType", "title", "transcript", "participants", "type" ] }, { "type": "object", "properties": { "eventTimestamp": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "string", "format": "date-time" } ] }, "eventType": { "type": "string", "enum": [ "opportunity_created", "deal_won", "deal_lost", "meeting_booked" ] }, "eventId": { "type": "string", "maxLength": 255 }, "opportunityId": { "type": "string", "maxLength": 200 }, "opportunityName": { "type": "string" }, "amount": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "currency": { "type": "string" }, "stage": { "type": "string" }, "stageCategory": { "type": "string", "enum": [ "open", "closed_won", "closed_lost", "other" ] }, "crmPipelineId": { "type": "string" }, "crmPipelineName": { "type": "string" }, "accountName": { "type": "string" }, "crmAccountId": { "type": "string" }, "crmAccountDomain": { "type": "string" }, "contactEmail": { "type": "string", "format": "email" }, "contactName": { "type": "string" }, "contactEmails": { "type": "array", "items": { "type": "string", "format": "email" } }, "ownerName": { "type": "string" }, "ownerEmail": { "type": "string", "format": "email" }, "crmOwnerId": { "type": "string" }, "closeDate": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "string", "format": "date-time" } ] }, "createdDate": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "string", "format": "date-time" } ] }, "crmLastModifiedAt": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "string", "format": "date-time" } ] }, "lossReason": { "type": "string" }, "mergedOpportunityIds": { "type": "array", "items": { "type": "string" } }, "sourceProviderName": { "type": "string" }, "customMetadata": { "type": "object", "additionalProperties": { "nullable": true } }, "type": { "type": "string", "enum": [ "crm" ] } }, "required": [ "eventTimestamp", "eventType", "opportunityId", "opportunityName", "type" ] }, { "type": "object", "properties": { "eventTimestamp": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "string", "format": "date-time" } ] }, "eventType": { "type": "string", "enum": [ "connection_sent", "connection_accepted", "message_sent", "message_received" ] }, "body": { "type": "object", "properties": { "text": { "type": "string" }, "html": { "type": "string" } } }, "from": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "email" ] }, "to": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" } }, "required": [ "email" ] }, "minItems": 1 }, "subject": { "type": "string" }, "eventId": { "type": "string", "maxLength": 255 }, "conversationId": { "type": "string" }, "campaignId": { "type": "string" }, "messageType": { "type": "string" }, "campaignName": { "type": "string" }, "octaveRequestId": { "type": "string" }, "crmOpportunityId": { "type": "string" }, "crmAccountId": { "type": "string" }, "crmAccountDomain": { "type": "string" }, "sourceProviderName": { "type": "string" }, "customMetadata": { "type": "object", "additionalProperties": { "nullable": true } }, "type": { "type": "string", "enum": [ "social" ] } }, "required": [ "eventTimestamp", "eventType", "body", "from", "to", "type" ] } ] }, "minItems": 1, "maxItems": 1000 }, "callbackUrl": { "type": "string", "format": "uri" } }, "required": [ "events" ], "description": "Up to 1000 events per request. Each event carries a `type` discriminator (`email` | `call` | `crm` | `social`) and otherwise follows the corresponding generic event structure used by the single-event webhook endpoints." } } } }, "responses": { "200": { "description": "Import jobs created", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "jobs": { "type": "array", "items": { "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "email", "call", "crm", "social" ], "description": "The event type this job covers" }, "provider": { "type": "string", "description": "The generic provider the events were imported under", "example": "OCTAVE_GENERIC_CALL" }, "jobOId": { "type": "string", "description": "The import job OId \u2014 poll GET /event/import/status with this value", "example": "pbj_3rgkoHhR00cEdE9DjKeIK" }, "accepted": { "type": "integer", "description": "Events queued for ingestion" }, "preSkipped": { "type": "integer", "description": "Events skipped immediately because the workspace already has an event with the same ID" }, "duplicatesInBatch": { "type": "array", "items": { "type": "integer" }, "description": "Zero-based request indices of events dropped because an earlier event in this request had the same ID" } }, "required": [ "eventType", "provider", "jobOId", "accepted", "preSkipped", "duplicatesInBatch" ] }, "description": "One import job per event type present in the request" }, "totalAccepted": { "type": "integer", "description": "Sum of accepted events across all jobs" }, "totalPreSkipped": { "type": "integer", "description": "Sum of pre-skipped events across all jobs" } }, "required": [ "_metadata", "jobs", "totalAccepted", "totalPreSkipped" ] } } } }, "400": { "description": "Validation failed \u2014 no events were imported. The message lists the offending event indices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/event/import/status": { "get": { "deprecated": false, "operationId": "getImportStatus", "summary": "Get bulk import status", "description": "Get the current status of a bulk event import job. Use this to poll for completion after POST /event/import. Recommended polling interval: 5\u201310 seconds. The job reaches COMPLETED only once every event is terminal \u2014 `ingested` is the authoritative success count.", "tags": [ "Events" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "The import job OId returned by POST /event/import", "example": "pbj_3rgkoHhR00cEdE9DjKeIK" }, "required": true, "description": "The import job OId returned by POST /event/import", "name": "jobOId", "in": "query" } ], "responses": { "200": { "description": "Import job status", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "type": "object", "properties": { "jobOId": { "type": "string", "description": "The import job OId" }, "provider": { "type": "string", "description": "The generic provider the events were imported under", "example": "OCTAVE_GENERIC_CALL" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "PAUSED", "COMPLETED", "FAILED", "CANCELLED" ], "description": "Job status. COMPLETED means every event reached a terminal state (ingested, skipped, or failed)." }, "counts": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total events tracked by this job" }, "pending": { "type": "integer", "description": "Events queued for ingestion" }, "published": { "type": "integer", "description": "Events accepted by the pipeline, awaiting ingestion confirmation" }, "ingested": { "type": "integer", "description": "Events successfully ingested \u2014 the authoritative success count" }, "skipped": { "type": "integer", "description": "Events deliberately not ingested (duplicates, non-processable event types, internal-only events)" }, "failed": { "type": "integer", "description": "Events that exhausted ingestion attempts" } }, "required": [ "total", "pending", "published", "ingested", "skipped", "failed" ], "description": "Per-status event counts" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string", "nullable": true, "description": "The event's dedupe ID (caller-supplied or content-derived)" }, "status": { "type": "string", "description": "The row status: FAILED or SKIPPED" }, "error": { "type": "string", "nullable": true, "description": "Why the event failed or was skipped" }, "attempts": { "type": "integer", "description": "Number of ingestion attempts made" } }, "required": [ "eventId", "status", "error", "attempts" ] }, "description": "Sample of failed/skipped events (failed first, capped at 20)" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the job was created" }, "startedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the job started processing" }, "completedAt": { "type": "string", "nullable": true, "format": "date-time", "description": "When the job reached a terminal state" } }, "required": [ "jobOId", "provider", "status", "counts", "errors", "createdAt", "startedAt", "completedAt" ] } }, "required": [ "_metadata", "data" ] } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/crm/get-entity-schema": { "get": { "operationId": "getEntitySchema", "summary": "Get CRM Entity Schema", "description": "Discover the valid fields/properties on a CRM entity (account, contact, lead, or opportunity) in the connected CRM (Salesforce or HubSpot). Introspect the schema first, then fetch fields by their real API names instead of guessing.", "tags": [ "CRM" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "enum": [ "account", "contact", "lead", "opportunity" ], "description": "CRM entity to introspect: account, contact, lead, or opportunity. Note: HubSpot does not support leads." }, "required": true, "description": "CRM entity to introspect: account, contact, lead, or opportunity. Note: HubSpot does not support leads.", "name": "entityType", "in": "query" }, { "schema": { "type": "string", "description": "Optional case-insensitive filter. Only fields whose API name, label, or description contains this substring are returned. Useful for locating a known field (e.g. 'qualification') without scanning the full property list." }, "required": false, "description": "Optional case-insensitive filter. Only fields whose API name, label, or description contains this substring are returned. Useful for locating a known field (e.g. 'qualification') without scanning the full property list.", "name": "search", "in": "query" } ], "responses": { "200": { "description": "Valid fields/properties for the CRM entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "provider": { "type": "string", "description": "Connected CRM provider (salesforce, hubspot) or 'none'" }, "entityType": { "type": "string", "enum": [ "account", "contact", "lead", "opportunity" ] }, "objectType": { "type": "string", "nullable": true, "description": "Provider-specific object name (e.g. 'contacts'/'companies' for HubSpot, 'Contact'/'Account' for Salesforce), or null when unsupported" }, "supported": { "type": "boolean", "description": "Whether this entity type is supported by the connected provider (e.g. HubSpot has no leads)" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "CRM API field/property name \u2014 the value to pass to additionalFields (e.g. 'qualification_rationale', 'Competitor__c')" }, "label": { "type": "string", "description": "Human-readable field label" }, "description": { "type": "string", "nullable": true, "description": "Field description / help text, when the CRM provides one" }, "type": { "type": "string", "description": "CRM data type (e.g. 'string', 'number', 'enumeration', 'datetime', 'bool')" }, "custom": { "type": "boolean", "description": "True for a custom (workspace-defined) field, false for a standard CRM field" }, "modifiable": { "type": "boolean", "description": "Whether the field can be written/updated. Read-only fields are still readable via additionalFields" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Human-readable option label" }, "value": { "type": "string", "description": "Underlying option value stored in the CRM" } }, "required": [ "label", "value" ] }, "description": "Allowed values for picklist / enumeration fields, when applicable" } }, "required": [ "name", "label", "type", "custom", "modifiable" ] }, "description": "Valid fields on the entity, sorted by label" }, "total": { "type": "number", "description": "Number of fields returned" } }, "required": [ "provider", "entityType", "objectType", "supported", "fields", "total" ] } }, "required": [ "data" ] } } } } } } }, "/api/v2/finding/list": { "get": { "operationId": "listFindings", "summary": "List Findings", "tags": [ "Findings" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "format": "date-time", "description": "Start of the time range (ISO 8601 datetime)" }, "required": false, "description": "Start of the time range (ISO 8601 datetime)", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "End of the time range (ISO 8601 datetime)" }, "required": false, "description": "End of the time range (ISO 8601 datetime)", "name": "endDate", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "maximum": 100, "default": 20, "description": "Maximum number of findings to return (max 100)" }, "required": false, "description": "Maximum number of findings to return (max 100)", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "default": 0, "description": "Number of findings to skip for pagination" }, "required": false, "description": "Number of findings to skip for pagination", "name": "offset", "in": "query" }, { "schema": { "type": "string", "enum": [ "EMAIL_INTERNAL_USE_CASE", "EMAIL_INTERNAL_PROOF_POINT", "EMAIL_INTERNAL_PAIN_POINT", "EMAIL_INTERNAL_BENEFITS_HIGHLIGHTED", "EMAIL_INTERNAL_VALUE_PROP", "EMAIL_INTERNAL_SOCIAL_PROOF", "EMAIL_INTERNAL_CALL_TO_ACTION", "EMAIL_INTERNAL_OBJECTION_HANDLING", "EMAIL_EXTERNAL_CALL_TO_ACTION", "EMAIL_EXTERNAL_OBJECTION", "EMAIL_EXTERNAL_QUESTION", "EMAIL_EXTERNAL_INTEREST_EXPRESSION", "EMAIL_EXTERNAL_FEATURE_REQUEST", "EMAIL_EXTERNAL_REQUIREMENT", "EMAIL_EXTERNAL_PRICING_FEEDBACK", "EMAIL_EXTERNAL_COMPARATIVE_STATEMENT", "EMAIL_EXTERNAL_KEY_TAKEAWAY", "EMAIL_EXTERNAL_COMPETITOR_MENTION", "EMAIL_EXTERNAL_NEXT_STEP", "EMAIL_EXTERNAL_URGENCY_INDICATOR", "EMAIL_EXTERNAL_DECISION_MAKING_SIGNAL", "EMAIL_EXTERNAL_UNIQUE_LANGUAGE_USED", "EMAIL_OVERALL_SENTIMENT", "EMAIL_TITLE_TO_PERSONA", "EMAIL_SEGMENT_DESCRIPTION", "SOCIAL_INTERNAL_USE_CASE", "SOCIAL_INTERNAL_PROOF_POINT", "SOCIAL_INTERNAL_PAIN_POINT", "SOCIAL_INTERNAL_VALUE_PROP", "SOCIAL_INTERNAL_SOCIAL_PROOF", "SOCIAL_INTERNAL_CALL_TO_ACTION", "SOCIAL_INTERNAL_BENEFITS_HIGHLIGHTED", "SOCIAL_INTERNAL_OBJECTION_HANDLING", "SOCIAL_TITLE_TO_PERSONA", "SOCIAL_SEGMENT_DESCRIPTION", "SOCIAL_PLAYBOOK_TOPICS", "SOCIAL_EXTERNAL_CALL_TO_ACTION", "SOCIAL_EXTERNAL_OBJECTION", "SOCIAL_EXTERNAL_QUESTION", "SOCIAL_EXTERNAL_INTEREST_EXPRESSION", "SOCIAL_EXTERNAL_FEATURE_REQUEST", "SOCIAL_EXTERNAL_REQUIREMENT", "SOCIAL_EXTERNAL_PRICING_FEEDBACK", "SOCIAL_EXTERNAL_COMPARATIVE_STATEMENT", "SOCIAL_EXTERNAL_KEY_TAKEAWAY", "SOCIAL_EXTERNAL_COMPETITOR_MENTION", "SOCIAL_EXTERNAL_NEXT_STEP", "SOCIAL_EXTERNAL_URGENCY_INDICATOR", "SOCIAL_EXTERNAL_DECISION_MAKING_SIGNAL", "SOCIAL_EXTERNAL_UNIQUE_LANGUAGE_USED", "SOCIAL_OVERALL_SENTIMENT", "CALL_EXTERNAL_BUSINESS_PROBLEMS", "CALL_EXTERNAL_IDEAL_SOLUTION_DESCRIPTION", "CALL_EXTERNAL_PRIMARY_GOALS", "CALL_EXTERNAL_WHY_ON_THIS_CALL", "CALL_EXTERNAL_STATUS_QUO_HOW_THEY_SOLVE_TODAY", "CALL_EXTERNAL_INDUSTRY_TRENDS", "CALL_EXTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_EXTERNAL_COMPETITORS_OF_THEIR_COMPANY", "CALL_EXTERNAL_CURRENT_TOOL_OR_SOLUTION_PROBLEMS", "CALL_EXTERNAL_OBJECTIONS", "CALL_EXTERNAL_PAIN_OR_PROBLEM_AGREEMENTS", "CALL_EXTERNAL_ROLE_OR_RESPONSIBILITIES_DESCRIPTION", "CALL_EXTERNAL_QUESTIONS_OR_CONFUSION_ABOUT_OFFERING", "CALL_EXTERNAL_CAPABILITIES_THAT_DREW_EXCITEMENT", "CALL_EXTERNAL_UNIQUE_LANGUAGE_USED", "CALL_EXTERNAL_FEATURE_REQUEST", "CALL_EXTERNAL_COMMITMENTS_MADE", "CALL_EXTERNAL_PRICING_OR_PACKAGING_FEEDBACK", "CALL_EXTERNAL_BLOCKERS_OR_DEPENDENCIES", "CALL_EXTERNAL_ABSENT_STAKEHOLDER_MENTIONS", "CALL_EXTERNAL_FRUSTRATION_OR_DISAPPOINTMENT", "CALL_EXTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_USE_CASES_BROUGHT_UP", "CALL_INTERNAL_PROOF_POINTS", "CALL_INTERNAL_REFERENCE_CUSTOMERS_OR_SOCIAL_PROOF", "CALL_INTERNAL_COMPETITORS", "CALL_INTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_INTERNAL_OBJECTION_HANDLING", "CALL_INTERNAL_VALUE_PROP_PRESENTATIONS", "CALL_INTERNAL_DIFFERENTIATED_VALUE", "CALL_INTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_COMPLEMENTARY_TOOLS_MENTIONED", "CALL_INTERNAL_COMMITMENTS_MADE", "CALL_COMPETITOR_MENTION_ORIGIN", "CALL_COMPETITOR_RELATIONSHIP_STATUS", "CALL_COMPETITOR_MENTAL_MODEL", "CALL_COMPETITOR_PROSPECT_VOICED_STRENGTH", "CALL_COMPETITOR_PROSPECT_VOICED_WEAKNESS", "CALL_COMPETITOR_OVERALL_STANCE", "CALL_COMPETITOR_HEAD_TO_HEAD_COMPARISON", "CALL_COMPETITOR_CONSIDERATION_SET_ALTERNATIVE", "CALL_COMPETITOR_COMMERCIAL_INTEL", "CALL_COMPETITOR_SWITCHING_TRIGGER_OR_BARRIER", "CALL_COMPETITOR_REP_CLAIM_REACTION", "CALL_COMPETITOR_DEAL_IMPACT", "CALL_CORE_FEATURE_MENTION_ORIGIN", "CALL_CORE_FEATURE_PROSPECT_LANGUAGE", "CALL_CORE_FEATURE_COMPREHENSION_CORRECTION", "CALL_CORE_FEATURE_PROSPECT_REACTION", "CALL_CORE_FEATURE_PROSPECT_QUESTION", "CALL_CORE_FEATURE_PROBLEM_ATTACHMENT", "CALL_CORE_FEATURE_VALUE_ARTICULATION", "CALL_CORE_FEATURE_CONCERN_OR_REQUIREMENT", "CALL_CORE_FEATURE_STATUS_QUO", "CALL_CORE_FEATURE_COMPARISON", "CALL_CORE_FEATURE_DECISION_WEIGHT", "CALL_CORE_FEATURE_USAGE_STAKEHOLDER", "RESOURCE_USE_CASES", "RESOURCE_PROOF_POINTS", "RESOURCE_REFERENCE_CUSTOMERS", "RESOURCE_COMPETITORS", "RESOURCE_OBJECTION_HANDLING", "RESOURCE_VALUE_PROPS", "RESOURCE_DIFFERENTIATED_VALUE", "RESOURCE_CORE_CAPABILITIES", "RESOURCE_SEGMENTS", "RESOURCE_INTEGRATIONS_PARTNERS", "RESOURCE_UNIQUE_LANGUAGE", "RESOURCE_PAIN_POINTS", "RESOURCE_TARGET_PERSONAS", "RESOURCE_ALTERNATIVES", "RESOURCE_BUYING_TRIGGERS", "CALL_OVERALL_SENTIMENT", "CALL_PURPOSE_CLASSIFICATION", "CALL_TITLE_TO_PERSONA", "CALL_SEGMENT_DESCRIPTION", "CRM_TITLE_TO_PERSONA", "CRM_SEGMENT_DESCRIPTION", "EVENT_SUMMARY", "BULK_IMPORT_THEMES", "BULK_LOSS_REASONS", "BULK_WIN_REASONS", "BULK_PAIN_POINTS", "BULK_USE_CASES", "BULK_COMPETITORS", "BULK_OBJECTIONS", "BULK_SEGMENTS", "BULK_PERSONAS", "ADS_INTERNAL_MESSAGING_THEME", "ADS_INTERNAL_TARGET_AUDIENCE", "ADS_INTERNAL_COMPETITIVE_POSITIONING", "ADS_INTERNAL_KEYWORD_TARGETING", "ADS_EXTERNAL_ENGAGEMENT_SIGNAL", "ADS_SEGMENT_DESCRIPTION", "ADS_MOTION_TYPE", "ADS_OFFERING_MATCH", "CALL_PROSPECT_RELATIONSHIP_TO_SELLER", "CALL_MOTION_TYPE", "CALL_OFFERING_MATCH", "EMAIL_PROSPECT_RELATIONSHIP_TO_SELLER", "EMAIL_MOTION_TYPE", "EMAIL_OFFERING_MATCH", "CRM_MOTION_TYPE", "CRM_OFFERING_MATCH", "RESOURCE_OFFERING_MATCH", "RESOURCE_TYPE_CLASSIFICATION", "CALL_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_TOPICS", "RESOURCE_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_SOURCE", "SOCIAL_PLAYBOOK_SOURCE", "CUSTOM" ], "description": "Filter by extraction type" }, "required": false, "description": "Filter by extraction type", "name": "extractionType", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "DISCOVERY", "DEMO", "TECHNICAL_EVALUATION", "WORKING_SESSION", "NEGOTIATION_PRICING", "ONBOARDING", "CHECK_IN_SUCCESS", "QBR_RENEWAL", "EXPANSION_UPSELL", "ESCALATION_CHURN_RISK", "SUPPORT", "INTERNAL_SYNC", "OTHER" ] }, "description": "Filter to findings from calls classified with any of these purposes (single value, repeated param, or comma-separated). Only call events carry a purpose, so this also narrows results to calls." }, "required": false, "description": "Filter to findings from calls classified with any of these purposes (single value, repeated param, or comma-separated). Only call events carry a purpose, so this also narrows results to calls.", "name": "callPurposes", "in": "query" } ], "responses": { "200": { "description": "List of extracted findings for the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "properties": { "oId": { "type": "string" }, "extractionType": { "type": "string", "enum": [ "EMAIL_INTERNAL_USE_CASE", "EMAIL_INTERNAL_PROOF_POINT", "EMAIL_INTERNAL_PAIN_POINT", "EMAIL_INTERNAL_BENEFITS_HIGHLIGHTED", "EMAIL_INTERNAL_VALUE_PROP", "EMAIL_INTERNAL_SOCIAL_PROOF", "EMAIL_INTERNAL_CALL_TO_ACTION", "EMAIL_INTERNAL_OBJECTION_HANDLING", "EMAIL_EXTERNAL_CALL_TO_ACTION", "EMAIL_EXTERNAL_OBJECTION", "EMAIL_EXTERNAL_QUESTION", "EMAIL_EXTERNAL_INTEREST_EXPRESSION", "EMAIL_EXTERNAL_FEATURE_REQUEST", "EMAIL_EXTERNAL_REQUIREMENT", "EMAIL_EXTERNAL_PRICING_FEEDBACK", "EMAIL_EXTERNAL_COMPARATIVE_STATEMENT", "EMAIL_EXTERNAL_KEY_TAKEAWAY", "EMAIL_EXTERNAL_COMPETITOR_MENTION", "EMAIL_EXTERNAL_NEXT_STEP", "EMAIL_EXTERNAL_URGENCY_INDICATOR", "EMAIL_EXTERNAL_DECISION_MAKING_SIGNAL", "EMAIL_EXTERNAL_UNIQUE_LANGUAGE_USED", "EMAIL_OVERALL_SENTIMENT", "EMAIL_TITLE_TO_PERSONA", "EMAIL_SEGMENT_DESCRIPTION", "SOCIAL_INTERNAL_USE_CASE", "SOCIAL_INTERNAL_PROOF_POINT", "SOCIAL_INTERNAL_PAIN_POINT", "SOCIAL_INTERNAL_VALUE_PROP", "SOCIAL_INTERNAL_SOCIAL_PROOF", "SOCIAL_INTERNAL_CALL_TO_ACTION", "SOCIAL_INTERNAL_BENEFITS_HIGHLIGHTED", "SOCIAL_INTERNAL_OBJECTION_HANDLING", "SOCIAL_TITLE_TO_PERSONA", "SOCIAL_SEGMENT_DESCRIPTION", "SOCIAL_PLAYBOOK_TOPICS", "SOCIAL_EXTERNAL_CALL_TO_ACTION", "SOCIAL_EXTERNAL_OBJECTION", "SOCIAL_EXTERNAL_QUESTION", "SOCIAL_EXTERNAL_INTEREST_EXPRESSION", "SOCIAL_EXTERNAL_FEATURE_REQUEST", "SOCIAL_EXTERNAL_REQUIREMENT", "SOCIAL_EXTERNAL_PRICING_FEEDBACK", "SOCIAL_EXTERNAL_COMPARATIVE_STATEMENT", "SOCIAL_EXTERNAL_KEY_TAKEAWAY", "SOCIAL_EXTERNAL_COMPETITOR_MENTION", "SOCIAL_EXTERNAL_NEXT_STEP", "SOCIAL_EXTERNAL_URGENCY_INDICATOR", "SOCIAL_EXTERNAL_DECISION_MAKING_SIGNAL", "SOCIAL_EXTERNAL_UNIQUE_LANGUAGE_USED", "SOCIAL_OVERALL_SENTIMENT", "CALL_EXTERNAL_BUSINESS_PROBLEMS", "CALL_EXTERNAL_IDEAL_SOLUTION_DESCRIPTION", "CALL_EXTERNAL_PRIMARY_GOALS", "CALL_EXTERNAL_WHY_ON_THIS_CALL", "CALL_EXTERNAL_STATUS_QUO_HOW_THEY_SOLVE_TODAY", "CALL_EXTERNAL_INDUSTRY_TRENDS", "CALL_EXTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_EXTERNAL_COMPETITORS_OF_THEIR_COMPANY", "CALL_EXTERNAL_CURRENT_TOOL_OR_SOLUTION_PROBLEMS", "CALL_EXTERNAL_OBJECTIONS", "CALL_EXTERNAL_PAIN_OR_PROBLEM_AGREEMENTS", "CALL_EXTERNAL_ROLE_OR_RESPONSIBILITIES_DESCRIPTION", "CALL_EXTERNAL_QUESTIONS_OR_CONFUSION_ABOUT_OFFERING", "CALL_EXTERNAL_CAPABILITIES_THAT_DREW_EXCITEMENT", "CALL_EXTERNAL_UNIQUE_LANGUAGE_USED", "CALL_EXTERNAL_FEATURE_REQUEST", "CALL_EXTERNAL_COMMITMENTS_MADE", "CALL_EXTERNAL_PRICING_OR_PACKAGING_FEEDBACK", "CALL_EXTERNAL_BLOCKERS_OR_DEPENDENCIES", "CALL_EXTERNAL_ABSENT_STAKEHOLDER_MENTIONS", "CALL_EXTERNAL_FRUSTRATION_OR_DISAPPOINTMENT", "CALL_EXTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_USE_CASES_BROUGHT_UP", "CALL_INTERNAL_PROOF_POINTS", "CALL_INTERNAL_REFERENCE_CUSTOMERS_OR_SOCIAL_PROOF", "CALL_INTERNAL_COMPETITORS", "CALL_INTERNAL_COMPETITORS_TO_OUR_OFFERING", "CALL_INTERNAL_OBJECTION_HANDLING", "CALL_INTERNAL_VALUE_PROP_PRESENTATIONS", "CALL_INTERNAL_DIFFERENTIATED_VALUE", "CALL_INTERNAL_CORE_CAPABILITIES", "CALL_INTERNAL_COMPLEMENTARY_TOOLS_MENTIONED", "CALL_INTERNAL_COMMITMENTS_MADE", "CALL_COMPETITOR_MENTION_ORIGIN", "CALL_COMPETITOR_RELATIONSHIP_STATUS", "CALL_COMPETITOR_MENTAL_MODEL", "CALL_COMPETITOR_PROSPECT_VOICED_STRENGTH", "CALL_COMPETITOR_PROSPECT_VOICED_WEAKNESS", "CALL_COMPETITOR_OVERALL_STANCE", "CALL_COMPETITOR_HEAD_TO_HEAD_COMPARISON", "CALL_COMPETITOR_CONSIDERATION_SET_ALTERNATIVE", "CALL_COMPETITOR_COMMERCIAL_INTEL", "CALL_COMPETITOR_SWITCHING_TRIGGER_OR_BARRIER", "CALL_COMPETITOR_REP_CLAIM_REACTION", "CALL_COMPETITOR_DEAL_IMPACT", "CALL_CORE_FEATURE_MENTION_ORIGIN", "CALL_CORE_FEATURE_PROSPECT_LANGUAGE", "CALL_CORE_FEATURE_COMPREHENSION_CORRECTION", "CALL_CORE_FEATURE_PROSPECT_REACTION", "CALL_CORE_FEATURE_PROSPECT_QUESTION", "CALL_CORE_FEATURE_PROBLEM_ATTACHMENT", "CALL_CORE_FEATURE_VALUE_ARTICULATION", "CALL_CORE_FEATURE_CONCERN_OR_REQUIREMENT", "CALL_CORE_FEATURE_STATUS_QUO", "CALL_CORE_FEATURE_COMPARISON", "CALL_CORE_FEATURE_DECISION_WEIGHT", "CALL_CORE_FEATURE_USAGE_STAKEHOLDER", "RESOURCE_USE_CASES", "RESOURCE_PROOF_POINTS", "RESOURCE_REFERENCE_CUSTOMERS", "RESOURCE_COMPETITORS", "RESOURCE_OBJECTION_HANDLING", "RESOURCE_VALUE_PROPS", "RESOURCE_DIFFERENTIATED_VALUE", "RESOURCE_CORE_CAPABILITIES", "RESOURCE_SEGMENTS", "RESOURCE_INTEGRATIONS_PARTNERS", "RESOURCE_UNIQUE_LANGUAGE", "RESOURCE_PAIN_POINTS", "RESOURCE_TARGET_PERSONAS", "RESOURCE_ALTERNATIVES", "RESOURCE_BUYING_TRIGGERS", "CALL_OVERALL_SENTIMENT", "CALL_PURPOSE_CLASSIFICATION", "CALL_TITLE_TO_PERSONA", "CALL_SEGMENT_DESCRIPTION", "CRM_TITLE_TO_PERSONA", "CRM_SEGMENT_DESCRIPTION", "EVENT_SUMMARY", "BULK_IMPORT_THEMES", "BULK_LOSS_REASONS", "BULK_WIN_REASONS", "BULK_PAIN_POINTS", "BULK_USE_CASES", "BULK_COMPETITORS", "BULK_OBJECTIONS", "BULK_SEGMENTS", "BULK_PERSONAS", "ADS_INTERNAL_MESSAGING_THEME", "ADS_INTERNAL_TARGET_AUDIENCE", "ADS_INTERNAL_COMPETITIVE_POSITIONING", "ADS_INTERNAL_KEYWORD_TARGETING", "ADS_EXTERNAL_ENGAGEMENT_SIGNAL", "ADS_SEGMENT_DESCRIPTION", "ADS_MOTION_TYPE", "ADS_OFFERING_MATCH", "CALL_PROSPECT_RELATIONSHIP_TO_SELLER", "CALL_MOTION_TYPE", "CALL_OFFERING_MATCH", "EMAIL_PROSPECT_RELATIONSHIP_TO_SELLER", "EMAIL_MOTION_TYPE", "EMAIL_OFFERING_MATCH", "CRM_MOTION_TYPE", "CRM_OFFERING_MATCH", "RESOURCE_OFFERING_MATCH", "RESOURCE_TYPE_CLASSIFICATION", "CALL_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_TOPICS", "RESOURCE_PLAYBOOK_TOPICS", "EMAIL_PLAYBOOK_SOURCE", "SOCIAL_PLAYBOOK_SOURCE", "CUSTOM" ] }, "snippetText": { "type": "string" }, "createdAt": { "type": "string", "nullable": true, "format": "date-time" }, "callPurpose": { "type": "string", "nullable": true, "enum": [ "DISCOVERY", "DEMO", "TECHNICAL_EVALUATION", "WORKING_SESSION", "NEGOTIATION_PRICING", "ONBOARDING", "CHECK_IN_SUCCESS", "QBR_RENEWAL", "EXPANSION_UPSELL", "ESCALATION_CHURN_RISK", "SUPPORT", "INTERNAL_SYNC", "OTHER", null ], "description": "Classified purpose of the finding's call. Null for non-call findings, for calls ingested before purpose classification stamped them, and for a stamped value no longer in the enum." } }, "required": [ "oId", "extractionType", "snippetText", "createdAt", "callPurpose" ] } }, "total": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "findings", "total", "hasMore" ] } }, "required": [ "data" ] } } } } } } }, "/api/v2/suggestion/list": { "get": { "deprecated": false, "operationId": "listSuggestions", "summary": "List Suggestions", "description": "List entity suggestions for the workspace \u2014 proposed library changes generated from analytics (calls, emails, deals) and other sources. Mirrors the Suggestions inbox: defaults to pending suggestions from the last 14 days. Each item includes its change type ('add' = new entity, 'refine' = change to an existing one), the entity name, the description (add) or instruction message (refine), and the reasoning.", "tags": [ "Suggestions" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "enum": [ "draft", "pending", "accepted", "rejected", "dismissed", "expired" ] }, "description": "Filter by status. Defaults to ['pending'] \u2014 the items awaiting review, matching the Suggestions inbox default." }, "required": false, "description": "Filter by status. Defaults to ['pending'] \u2014 the items awaiting review, matching the Suggestions inbox default.", "name": "statuses", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "add", "refine" ] }, "description": "Filter by change type: 'add' (new entity) or 'refine' (change to an existing one). Omit to include both." }, "required": false, "description": "Filter by change type: 'add' (new entity) or 'refine' (change to an existing one). Omit to include both.", "name": "changeTypes", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "Agent", "Hypothesis", "BrandVoice", "Resource" ] }, "description": "Filter by the library entity type being added or refined (e.g. Persona, Product, UseCase, Competitor). Omit to include all." }, "required": false, "description": "Filter by the library entity type being added or refined (e.g. Persona, Product, UseCase, Competitor). Omit to include all.", "name": "targetEntityTypes", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Look back this many days from now. Defaults to 14 (the inbox default). Ignored when startDate is provided." }, "required": false, "description": "Look back this many days from now. Defaults to 14 (the inbox default). Ignored when startDate is provided.", "name": "daysBack", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "description": "Only include suggestions created on or after this date (ISO 8601). Overrides daysBack when set." }, "required": false, "description": "Only include suggestions created on or after this date (ISO 8601). Overrides daysBack when set.", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "nullable": true, "format": "date-time", "description": "Only include suggestions created on or before this date (ISO 8601)." }, "required": false, "description": "Only include suggestions created on or before this date (ISO 8601).", "name": "endDate", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "analytics", "brand_voice", "user_created", "ask_octave", "ask_octave_manual", "resource", "crm_import", "direct_findings", "trends" ] }, "description": "Restrict to suggestions originating from these sources (e.g. ANALYTICS, DIRECT_FINDINGS, USER_CREATED). Omit to include all sources." }, "required": false, "description": "Restrict to suggestions originating from these sources (e.g. ANALYTICS, DIRECT_FINDINGS, USER_CREATED). Omit to include all sources.", "name": "sourceTypes", "in": "query" }, { "schema": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "maximum": 100, "default": 20, "description": "Max results to return (1-100, default 20)." }, "required": false, "description": "Max results to return (1-100, default 20).", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Pagination offset (default 0)." }, "required": false, "description": "Pagination offset (default 0).", "name": "offset", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort by createdAt. Defaults to 'desc' (newest first)." }, "required": false, "description": "Sort by createdAt. Defaults to 'desc' (newest first).", "name": "sortDirection", "in": "query" } ], "responses": { "200": { "description": "List of entity suggestions for the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestionListItem" } }, "total": { "type": "number", "description": "Total suggestions matching the filters." }, "counts": { "type": "object", "properties": { "pending": { "type": "number" }, "accepted": { "type": "number" }, "rejected": { "type": "number" } }, "required": [ "pending", "accepted", "rejected" ], "description": "Status counts across the timeframe/filters, ignoring the status filter." }, "nextOffset": { "type": "number", "nullable": true, "description": "Offset for the next page, or null when there are no more results." } }, "required": [ "_metadata", "suggestions", "total", "counts", "nextOffset" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/suggestion/get": { "get": { "deprecated": false, "operationId": "getSuggestion", "summary": "Get Suggestion", "description": "Preview a single entity suggestion in full. For 'add' suggestions, returns the complete proposed new entity. For 'refine' suggestions, returns both the current entity and what it would look like after the change, so you can show the diff. Optionally include the supporting evidence (events/findings) that generated it.", "tags": [ "Suggestions" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "The suggestion oId to preview. Get this from suggestion/list.", "example": "esug_abc123" }, "required": true, "description": "The suggestion oId to preview. Get this from suggestion/list.", "name": "oId", "in": "query" }, { "schema": { "type": "boolean", "default": true, "description": "When true (default), also returns the rendered preview: for 'add' the full proposed new entity, for 'refine' the entity as it would look after the change (plus the current entity to diff against). Set to false for a fast metadata-only fetch that skips preview generation." }, "required": false, "description": "When true (default), also returns the rendered preview: for 'add' the full proposed new entity, for 'refine' the entity as it would look after the change (plus the current entity to diff against). Set to false for a fast metadata-only fetch that skips preview generation.", "name": "includePreview", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, also returns the supporting events/findings that generated this suggestion (the 'why'). Defaults to false." }, "required": false, "description": "When true, also returns the supporting events/findings that generated this suggestion (the 'why'). Defaults to false.", "name": "includeEvidence", "in": "query" }, { "schema": { "type": "boolean", "default": false, "description": "When true, also returns diffChunks \u2014 before/after diff chunks for the proposed change. For entity refine suggestions these are field-level diffs of the current entity vs the previewed result; for doc-update suggestions they are anchored hunks validated against the doc, each with a clean/stale/unverified status. Defaults to false to keep responses small." }, "required": false, "description": "When true, also returns diffChunks \u2014 before/after diff chunks for the proposed change. For entity refine suggestions these are field-level diffs of the current entity vs the previewed result; for doc-update suggestions they are anchored hunks validated against the doc, each with a clean/stale/unverified status. Defaults to false to keep responses small.", "name": "includeDiff", "in": "query" } ], "responses": { "200": { "description": "The suggestion detail (and preview, unless skipped)", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/SuggestionDetail" } }, "required": [ "_metadata", "data" ] } } } }, "404": { "description": "Suggestion not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/suggestion/create": { "post": { "deprecated": false, "operationId": "createSuggestion", "summary": "Create Suggestion", "description": "Queue a PENDING entity suggestion for human review. This does NOT create or modify any library entity \u2014 it produces a proposal that must be explicitly accepted (via suggestion/accept or the Suggestions inbox) before anything changes. Set changeType to 'add' (with name) to propose a new entity, or 'refine' (with the target entity oId) to propose changes to an existing one.", "tags": [ "Suggestions" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "changeType": { "type": "string", "enum": [ "add", "refine" ], "description": "'add' proposes a brand new entity; 'refine' proposes changes to an existing one.", "example": "add" }, "entityType": { "type": "string", "enum": [ "persona", "product", "segment", "use_case", "competitor", "alternative", "buying_trigger", "core_feature", "objection", "proof_point", "reference", "service", "solution", "brand_voice" ], "description": "Library entity type: persona, product, segment, use_case, competitor, alternative, buying_trigger, objection, proof_point, reference, service, solution, brand_voice.", "example": "persona" }, "name": { "type": "string", "description": "Name of the new entity. Required when changeType is 'add'." }, "oId": { "type": "string", "description": "oId of the entity to refine (from the entity list endpoints). Required when changeType is 'refine'." }, "instructions": { "type": "string", "description": "Detailed natural-language description of what to add or change, and why." }, "keyContext": { "type": "string", "description": "Additional background text to inform the proposal." }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url", "text" ], "description": "Source type: 'url' for web pages, 'text' for raw content" }, "content": { "type": "string", "description": "The URL to fetch or the text content" } }, "required": [ "type", "content" ] }, "description": "Optional source materials (URLs to fetch, or raw text) to inform the proposal." } }, "required": [ "changeType", "entityType", "instructions" ] } } } }, "responses": { "200": { "description": "The queued pending suggestion", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/SuggestionCreateResult" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Missing required field for the change type (name for 'add', oId for 'refine'), or invalid input", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "403": { "description": "Plan does not include this entity type", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/suggestion/update": { "post": { "deprecated": false, "operationId": "updateSuggestion", "summary": "Update Suggestion", "description": "Edit a PENDING entity suggestion before accepting it. Two combinable modes: `instructions` regenerates the proposed content via AI; `edits` applies a precise partial field override with no regeneration. Works for both 'add' and 'refine' suggestions. Returns the updated preview. The suggestion stays pending \u2014 nothing is applied until you call suggestion/accept.", "tags": [ "Suggestions" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "The suggestion oId to revise (from suggestion/list). Only pending suggestions can be revised.", "example": "esug_abc123" }, "instructions": { "type": "string", "description": "REGENERATE mode. Natural-language instructions for how to change the proposal \u2014 e.g. 'make the description more concise'. The proposed content is regenerated by AI. Combine with `edits` to regenerate first, then apply precise overrides on top." }, "edits": { "type": "object", "additionalProperties": { "nullable": true }, "description": "OVERRIDE mode. A partial patch of fields on the proposed entity \u2014 only the keys you provide change; arrays replace wholesale, objects deep-merge. No AI regeneration runs. Use this to surgically fix one detail of an otherwise-good proposal. Inspect the current proposal with suggestion/get first to see the field shape." }, "mode": { "type": "string", "enum": [ "replace", "append" ], "default": "replace", "description": "Applies to `instructions` only: 'replace' (default) swaps the prior instruction for this one; 'append' layers it on top." } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "The revised suggestion preview", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/SuggestionDetail" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Neither instructions nor edits provided, or suggestion not pending", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Suggestion not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/suggestion/accept": { "post": { "deprecated": false, "operationId": "acceptSuggestion", "summary": "Accept Suggestion", "description": "Accept a pending entity suggestion. This APPLIES the proposed change \u2014 for an 'add' suggestion it creates the new library entity; for a 'refine' suggestion it updates the existing one. Preview first with suggestion/get. Returns the resulting library entity.", "tags": [ "Suggestions" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "The suggestion oId to accept (from suggestion/list). Only pending suggestions can be accepted.", "example": "esug_abc123" }, "reason": { "type": "string", "description": "Optional note recording why the suggestion was accepted." } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "The accepted suggestion and resulting entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/SuggestionAcceptResult" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Suggestion is not pending or cannot be accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Suggestion not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/suggestion/reject": { "post": { "deprecated": false, "operationId": "rejectSuggestion", "summary": "Reject Suggestion", "description": "Reject a pending entity suggestion. This does NOT change any library entity \u2014 it marks the proposed change as dismissed so it no longer appears in the pending queue. An optional reason can be recorded.", "tags": [ "Suggestions" ], "x-visibility": "public", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "oId": { "type": "string", "description": "The suggestion oId to reject (from suggestion/list). Only pending suggestions can be rejected.", "example": "esug_abc123" }, "reason": { "type": "string", "description": "Optional reason for rejecting. Recording one helps the system learn from rejected suggestions." } }, "required": [ "oId" ] } } } }, "responses": { "200": { "description": "The rejected suggestion", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/SuggestionRejectResult" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Suggestion is not pending or cannot be rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Suggestion not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/revision/list": { "get": { "operationId": "listRevisions", "summary": "List Revisions", "description": "List audit-trail revisions for library and agent entities, with optional filters by entity type, entity oIds, date range, and author. Returns lightweight summaries \u2014 use `getRevision` to fetch a single revision's full before/after state or diff.", "tags": [ "Revisions" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "array", "items": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "ContentAgent", "Hypothesis", "WorkspaceCompany", "WritingStyle", "BrandVoice", "ChainedAgentWorkflow", "SmartExample", "Skill" ] }, "description": "Optional list of entity types to filter revisions to (Persona, Product, Service, Solution, Segment, UseCase, Competitor, Alternative, BuyingTrigger, Objection, ProofPoint, Reference, Playbook, ContentAgent, Hypothesis, WorkspaceCompany, WritingStyle, BrandVoice, ChainedAgentWorkflow, SmartExample)." }, "required": false, "description": "Optional list of entity types to filter revisions to (Persona, Product, Service, Solution, Segment, UseCase, Competitor, Alternative, BuyingTrigger, Objection, ProofPoint, Reference, Playbook, ContentAgent, Hypothesis, WorkspaceCompany, WritingStyle, BrandVoice, ChainedAgentWorkflow, SmartExample).", "name": "entityTypes", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string" }, "maxItems": 20, "description": "Optional list of entity oIds (e.g. 'pe_*' for persona, 'pb_*' for playbook) to constrain the search to revisions of those specific entities. Capped at 20." }, "required": false, "description": "Optional list of entity oIds (e.g. 'pe_*' for persona, 'pb_*' for playbook) to constrain the search to revisions of those specific entities. Capped at 20.", "name": "entityOIds", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Optional ISO 8601 start date \u2014 return revisions created on or after this date." }, "required": false, "description": "Optional ISO 8601 start date \u2014 return revisions created on or after this date.", "name": "startDate", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Optional ISO 8601 end date \u2014 return revisions created on or before this date." }, "required": false, "description": "Optional ISO 8601 end date \u2014 return revisions created on or before this date.", "name": "endDate", "in": "query" }, { "schema": { "type": "string", "description": "Optional user oId (e.g. 'u_*') to filter revisions to changes authored by a specific user." }, "required": false, "description": "Optional user oId (e.g. 'u_*') to filter revisions to changes authored by a specific user.", "name": "authorOId", "in": "query" }, { "schema": { "type": "boolean", "description": "If true, include revisions that have already been restored. Defaults to false." }, "required": false, "description": "If true, include revisions that have already been restored. Defaults to false.", "name": "includeRestored", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Maximum number of revisions to return (default 25, max 100)." }, "required": false, "description": "Maximum number of revisions to return (default 25, max 100).", "name": "limit", "in": "query" }, { "schema": { "type": "integer", "nullable": true, "minimum": 0, "default": 0, "description": "Pagination offset (default 0)." }, "required": false, "description": "Pagination offset (default 0).", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of revisions for the workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revisions": { "type": "array", "items": { "type": "object", "properties": { "revisionOId": { "type": "string", "description": "Revision oId (ev_* prefix)." }, "summary": { "type": "string", "nullable": true, "description": "LLM-generated summary of the changes captured by this revision." }, "entityName": { "type": "string", "nullable": true, "description": "Display name of the entity at the time of the revision." }, "entityType": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "ContentAgent", "Hypothesis", "WorkspaceCompany", "WritingStyle", "BrandVoice", "ChainedAgentWorkflow", "SmartExample", "Skill" ], "description": "Type of the entity." }, "entityOId": { "type": "string", "nullable": true, "description": "The entity's oId (from the stored entityData)." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the revision was created." }, "authorName": { "type": "string", "nullable": true, "description": "Display name of the user who authored the revision, when known." } }, "required": [ "revisionOId", "summary", "entityName", "entityType", "entityOId", "createdAt", "authorName" ] } }, "total": { "type": "integer", "description": "Total number of revisions matching the filters." }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "revisions", "total", "limit", "offset" ] } }, "required": [ "data" ] } } } } } } }, "/api/v2/revision/get": { "get": { "operationId": "getRevision", "summary": "Get Revision", "description": "Fetch a single audit-trail revision by oId. Returns the before/after entity snapshots plus a recursive field-level diff (added / removed / changed) that descends into nested objects. Arrays are treated as atomic leaves. Pass `diffOnly: true` to omit the full snapshots and return only the diff \u2014 useful when the entity is large and you only care about what changed.", "tags": [ "Revisions" ], "x-visibility": "public", "parameters": [ { "schema": { "type": "string", "description": "The oId of the revision to fetch (ev_* prefix). Use `listRevisions` to discover revision oIds." }, "required": true, "description": "The oId of the revision to fetch (ev_* prefix). Use `listRevisions` to discover revision oIds.", "name": "revisionOId", "in": "query" }, { "schema": { "type": "boolean", "description": "If true, return only the field-level diff (added / removed / changed) instead of the full before-and-after entity snapshots. Defaults to false." }, "required": false, "description": "If true, return only the field-level diff (added / removed / changed) instead of the full before-and-after entity snapshots. Defaults to false.", "name": "diffOnly", "in": "query" } ], "responses": { "200": { "description": "The requested revision detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "revisionOId": { "type": "string" }, "summary": { "type": "string", "nullable": true, "description": "LLM-generated summary of the changes captured by this revision." }, "entityType": { "type": "string", "enum": [ "Product", "Service", "Solution", "Persona", "UseCase", "Reference", "Segment", "Competitor", "Alternative", "BuyingTrigger", "CoreFeature", "Objection", "ProofPoint", "Playbook", "ContentAgent", "Hypothesis", "WorkspaceCompany", "WritingStyle", "BrandVoice", "ChainedAgentWorkflow", "SmartExample", "Skill" ], "description": "Type of the entity this revision belongs to." }, "entityOId": { "type": "string", "nullable": true, "description": "oId of the entity this revision belongs to. Null in the rare case the stored revision payload doesn't carry one." }, "entityName": { "type": "string", "nullable": true, "description": "Display name of the entity at the time of the revision." }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when the revision was created." }, "authorName": { "type": "string", "nullable": true, "description": "Display name of the user who authored the revision, when known." }, "newEntity": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "Full snapshot of the entity captured by this revision. Null when `diffOnly` is true." }, "oldEntity": { "type": "object", "nullable": true, "additionalProperties": { "nullable": true }, "description": "Snapshot of the entity just before this revision (null for the first revision of an entity). Null when `diffOnly` is true." }, "diff": { "allOf": [ { "$ref": "#/components/schemas/EntityRevisionDiff" }, { "description": "Recursive field-level diff between oldEntity and newEntity. Always returned, even when `diffOnly` is false." } ] } }, "required": [ "revisionOId", "summary", "entityType", "entityOId", "entityName", "createdAt", "authorName", "newEntity", "oldEntity", "diff" ] } }, "required": [ "data" ] } } } } } } }, "/api/v2/workspace-company/get": { "get": { "deprecated": false, "operationId": "getWorkspaceCompany", "summary": "Get Workspace Company", "description": "Get the workspace company. There is exactly one workspace company per workspace; the caller's workspace is inferred from the API key.", "tags": [ "Workspace Company" ], "x-visibility": "public", "responses": { "200": { "description": "Workspace Company data", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/WorkspaceCompany" } }, "required": [ "_metadata", "data" ] } } } }, "404": { "description": "Workspace Company not found for this workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/workspace-company/update": { "post": { "deprecated": false, "operationId": "updateWorkspaceCompany", "summary": "Update Workspace Company", "description": "Update the workspace company. There is exactly one workspace company per workspace; the caller's workspace is inferred from the API key.", "tags": [ "Workspace Company" ], "x-visibility": "public", "requestBody": { "description": "Workspace Company update input", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The external name of the workspace company", "example": "Acme Corp" }, "internalName": { "type": "string", "description": "The internal name of the workspace company", "example": "Acme" }, "description": { "type": "string", "description": "A description of the workspace company", "example": "Acme builds GTM tooling for B2B SaaS teams." }, "url": { "type": "string", "description": "The website URL for the workspace company", "example": "https://acme.com" }, "whyWeExist": { "type": "array", "items": { "type": "string" }, "description": "Why the company exists", "example": [ "Help B2B teams scale outbound without losing personalization" ] }, "howWePositionOurselves": { "type": "array", "items": { "type": "string" }, "description": "How the company positions itself in the market", "example": [ "The first sales platform built around the buying journey" ] }, "whoWeHelp": { "type": "array", "items": { "type": "string" }, "description": "Who the company helps", "example": [ "B2B sales teams at high-growth SaaS companies" ] }, "whatMakesUsUnique": { "type": "array", "items": { "type": "string" }, "description": "What makes the company unique", "example": [ "Bidirectional knowledge graph connecting library to outcomes" ] }, "businessModel": { "type": "array", "items": { "type": "string" }, "description": "The company's business model", "example": [ "Annual subscription, seat-based pricing" ] }, "marketDynamics": { "type": "array", "items": { "type": "string" }, "description": "Market dynamics the company operates within", "example": [ "AI-driven sales tooling consolidation" ] }, "whyCustomersBuy": { "type": "array", "items": { "type": "string" }, "description": "Why customers buy", "example": [ "Higher reply rates without expanding the SDR team" ] }, "whyCustomersCare": { "type": "array", "items": { "type": "string" }, "description": "Why customers care", "example": [ "Sales productivity directly drives revenue growth" ] }, "customFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom fields for additional workspace company information" } ] }, "customMarketFields": { "allOf": [ { "$ref": "#/components/schemas/CustomDataFields" }, { "description": "Custom market-specific fields" } ] } } } } } }, "responses": { "200": { "description": "Workspace Company updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/WorkspaceCompany" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } }, "404": { "description": "Workspace Company not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/workspace-company/generate": { "post": { "deprecated": false, "operationId": "generateWorkspaceCompany", "summary": "Generate Workspace Company", "description": "Generate workspace company content from a domain, free-form source materials (text, URLs, or Resource references), or both. At least one of `domain` or `sources` is required. When `domain` is provided it is scraped; when `sources` are provided they are expanded; both feed the workspace builder LLM. The result is persisted: the existing workspace company is updated in place, or one is created if it does not exist.", "tags": [ "Workspace Company" ], "x-visibility": "public", "requestBody": { "description": "Workspace Company generation input", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "description": "The domain or URL to scrape and generate the workspace company from. Optional if `sources` is provided.", "example": "acme.com" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT", "URL", "RESOURCE" ], "description": "The type of source material", "example": "TEXT" }, "value": { "type": "string", "minLength": 1, "description": "The source content (text, URL, or name)", "example": "Lead generation and qualification for enterprise sales" } }, "required": [ "type", "value" ] }, "description": "Optional source materials (text or URLs) to feed into the workspace company generation. At least one of `domain` or `sources` must be provided. When both are provided, the scraped domain content and the expanded sources are combined.", "example": [ { "type": "TEXT", "value": "We are a stealth-mode B2B platform helping mid-market RevOps teams unify pipeline data." } ] } } } } } }, "responses": { "200": { "description": "Workspace Company generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "data": { "$ref": "#/components/schemas/WorkspaceCompany" } }, "required": [ "_metadata", "data" ] } } } }, "400": { "description": "Bad request - unable to scrape domain or generate content", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/person/resolve-profile": { "post": { "deprecated": false, "operationId": "resolveProfile", "summary": "Resolve Profile from Email", "description": "Resolve a person's LinkedIn profile, title, company, and location from their email (or name + company / LinkedIn URL) using Octave's enrichment data. Supports a confidence threshold and an optional thorough effort mode with LLM validation. Charges credits only when a profile is found at or above the requested confidence.", "tags": [ "Research" ], "x-visibility": "public", "requestBody": { "description": "Identifiers to resolve a profile from", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "nullable": true, "format": "email", "description": "Email address to resolve a profile from. The primary identifier for the signup use case.", "example": "jane@acme.com" }, "firstName": { "type": "string", "nullable": true, "description": "Optional first name to improve match accuracy" }, "lastName": { "type": "string", "nullable": true, "description": "Optional last name to improve match accuracy" }, "linkedInProfile": { "type": "string", "nullable": true, "description": "Optional LinkedIn profile URL or slug. When provided it is the strongest identifier.", "example": "https://www.linkedin.com/in/jane-doe" }, "companyName": { "type": "string", "nullable": true, "description": "Optional company name to disambiguate" }, "companyDomain": { "type": "string", "nullable": true, "description": "Optional company domain to disambiguate" }, "minConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "default": "LOW", "description": "Minimum match confidence required for a result to count as found. Matches below this are returned as found=false (no credits charged)." }, "effort": { "type": "string", "enum": [ "standard", "thorough" ], "default": "standard", "description": "`standard` does a single exact lookup; `thorough` adds fallback strategies and an LLM validation pass." } } } } } }, "responses": { "200": { "description": "Resolution result (found may be false)", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether a profile met the confidence threshold" }, "profile": { "$ref": "#/components/schemas/ResolvedProfile" }, "confidence": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", null ], "description": "Confidence of the (best) match, if any" }, "meetsConfidenceThreshold": { "type": "boolean", "description": "Whether the best match's confidence is >= the requested minConfidence" }, "effort": { "type": "string", "enum": [ "standard", "thorough" ] }, "creditsCharged": { "type": "number", "description": "Credits charged for this call (0 if not found)" }, "message": { "type": "string", "nullable": true } }, "required": [ "_metadata", "found", "meetsConfidenceThreshold", "effort", "creditsCharged" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } }, "/api/v2/person/resolve-email": { "post": { "deprecated": false, "operationId": "resolveEmail", "summary": "Resolve Email from Profile", "description": "Resolve the best work email for a person from their LinkedIn profile (or name + company) using Octave's enrichment data, with a deliverability status. The reverse of resolveProfile. Supports a confidence threshold and an optional thorough effort mode. Charges credits only when a deliverable email is found at or above the requested confidence.", "tags": [ "Research" ], "x-visibility": "public", "requestBody": { "description": "Identifiers to resolve an email from", "content": { "application/json": { "schema": { "type": "object", "properties": { "linkedInProfile": { "type": "string", "nullable": true, "description": "LinkedIn profile URL or slug. The strongest identifier for resolving an email.", "example": "https://www.linkedin.com/in/jane-doe" }, "firstName": { "type": "string", "nullable": true, "description": "First name (used with company when no LinkedIn)" }, "lastName": { "type": "string", "nullable": true, "description": "Last name (used with company when no LinkedIn)" }, "companyName": { "type": "string", "nullable": true, "description": "Company name (used with name when no LinkedIn)" }, "companyDomain": { "type": "string", "nullable": true, "description": "Company domain (used with name when no LinkedIn)" }, "minConfidence": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "default": "LOW", "description": "Minimum confidence required for the email to count as found. Lower-confidence emails are returned as found=false (no credits charged)." }, "effort": { "type": "string", "enum": [ "standard", "thorough" ], "default": "standard", "description": "`standard` resolves the profile via the strongest identifier only; `thorough` also tries the alternate resolution path." } } } } } }, "responses": { "200": { "description": "Resolution result (found may be false)", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "found": { "type": "boolean", "description": "Whether an email met the confidence threshold" }, "email": { "type": "string", "nullable": true, "example": "jane@acme.com" }, "emailStatus": { "type": "string", "nullable": true, "enum": [ "valid", "invalid", "accept_all", "webmail", "catchall", "disposable", "unknown", "not_found", null ], "description": "Deliverability status from the email provider" }, "confidence": { "type": "string", "nullable": true, "enum": [ "LOW", "MEDIUM", "HIGH", null ] }, "meetsConfidenceThreshold": { "type": "boolean" }, "effort": { "type": "string", "enum": [ "standard", "thorough" ] }, "creditsCharged": { "type": "number", "description": "Credits charged for this call (0 if not found)" }, "matchedProfile": { "type": "object", "nullable": true, "properties": { "firstName": { "type": "string", "nullable": true, "example": "Jane" }, "lastName": { "type": "string", "nullable": true, "example": "Doe" }, "fullName": { "type": "string", "nullable": true, "example": "Jane Doe" }, "title": { "type": "string", "nullable": true, "example": "VP of Engineering" }, "headline": { "type": "string", "nullable": true, "description": "LinkedIn headline" }, "seniority": { "type": "string", "nullable": true, "description": "Normalized current seniority" }, "jobFunction": { "type": "string", "nullable": true, "description": "Normalized current job function" }, "linkedInUrl": { "type": "string", "nullable": true, "example": "https://www.linkedin.com/in/jane-doe" }, "linkedInSlug": { "type": "string", "nullable": true, "example": "jane-doe" }, "companyName": { "type": "string", "nullable": true, "example": "Acme" }, "companyDomain": { "type": "string", "nullable": true, "example": "acme.com" }, "companyLinkedInUrl": { "type": "string", "nullable": true }, "location": { "type": "string", "nullable": true, "example": "San Francisco, CA" }, "city": { "type": "string", "nullable": true, "example": "San Francisco" }, "countryCode": { "type": "string", "nullable": true, "example": "US" }, "summary": { "type": "string", "nullable": true }, "photoUrl": { "type": "string", "nullable": true } }, "description": "The profile the email was resolved for" }, "message": { "type": "string", "nullable": true } }, "required": [ "_metadata", "found", "meetsConfidenceThreshold", "effort", "creditsCharged" ] } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "_metadata": { "$ref": "#/components/schemas/Metadata" }, "message": { "type": "string" } }, "required": [ "_metadata", "message" ] } } } } } } } } }