openapi: 3.0.3
info:
  title: traxy Customer API and MCP V1
  version: 1.0.0
  description: |
    Public customer-facing read API, Ordinal Audience Analytics endpoints, and
    remote MCP Streamable HTTP endpoint. Customer REST and Ordinal requests use
    bearer API keys. MCP uses OAuth access tokens issued for the traxy MCP
    resource; API keys are not accepted by MCP. Public REST clients must
    not send organizationId. Default API keys cover the general read API.
    Ordinal Audience Analytics is self-serve for paid workspaces and requires
    explicitly selected audience_analytics scopes on the key.
    The current MCP surface exposes 42 scope-gated tools through tools/list,
    including confirmed lead, Agent, Watchlist, post, and delivery actions. Latest
    MCP protocol examples use 2025-11-25; 2025-06-18 remains legacy-compatible.
servers:
  - url: https://api.traxy.ai/api/v1
    description: Production
security:
  - CustomerApiKey: []
tags:
  - name: Customer REST
  - name: Ordinal Audience Analytics
  - name: MCP OAuth
  - name: MCP
paths:
  /customer/workspace-access:
    get:
      tags: [Customer REST]
      summary: Get business-facing workspace data access.
      security:
        - CustomerApiKey: [workspace:read]
      responses:
        '200':
          description: Workspace capabilities and usage available to this key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceAccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
        '429':
          $ref: '#/components/responses/RateLimited'
  /customer/leads:
    get:
      tags: [Customer REST]
      summary: List active leads available to this key.
      security:
        - CustomerApiKey: [leads:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/LeadTierFilter'
        - $ref: '#/components/parameters/LeadTiersFilter'
        - $ref: '#/components/parameters/LeadDispositionFilter'
        - $ref: '#/components/parameters/LeadDispositionsFilter'
        - $ref: '#/components/parameters/MinIcpMatchPercentFilter'
        - $ref: '#/components/parameters/MaxIcpMatchPercentFilter'
        - $ref: '#/components/parameters/MonitoredProfileIdFilter'
        - $ref: '#/components/parameters/MonitoredProfileIdsFilter'
        - $ref: '#/components/parameters/PostIdFilter'
        - $ref: '#/components/parameters/EngagementTypeFilter'
        - $ref: '#/components/parameters/EngagementTypesFilter'
        - $ref: '#/components/parameters/OwnerIdFilter'
        - $ref: '#/components/parameters/OwnerIdsFilter'
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
        - $ref: '#/components/parameters/SearchQueryFilter'
        - $ref: '#/components/parameters/CompanyNamesFilter'
        - $ref: '#/components/parameters/LeadOriginFilter'
      responses:
        '200':
          description: Lead page. Contact fields are null unless the key has leads:contact_read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeadPage'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
        '429':
          $ref: '#/components/responses/RateLimited'
  /customer/leads/signals:
    get:
      tags: [Customer REST]
      summary: List lead signals with safe lead, post, and Watchlist context.
      security:
        - CustomerApiKey: [leads:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/LeadIdFilter'
        - $ref: '#/components/parameters/MonitoredProfileIdFilter'
        - $ref: '#/components/parameters/MonitoredProfileIdsFilter'
        - $ref: '#/components/parameters/PostIdFilter'
        - $ref: '#/components/parameters/EngagementTypeFilter'
        - $ref: '#/components/parameters/EngagementTypesFilter'
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
        - $ref: '#/components/parameters/MinIcpMatchPercentFilter'
        - $ref: '#/components/parameters/MaxIcpMatchPercentFilter'
        - $ref: '#/components/parameters/LeadDispositionFilter'
        - $ref: '#/components/parameters/SearchQueryFilter'
        - $ref: '#/components/parameters/CompanyNamesFilter'
        - $ref: '#/components/parameters/ProfileTypeFilter'
        - $ref: '#/components/parameters/RelationshipLabelFilter'
        - $ref: '#/components/parameters/LeadOriginFilter'
      responses:
        '200':
          $ref: '#/components/responses/PageObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
        '429':
          $ref: '#/components/responses/RateLimited'
  /customer/leads/counts:
    get:
      tags: [Customer REST]
      summary: Get active lead counts.
      security:
        - CustomerApiKey: [leads:read]
      responses:
        '200':
          description: Lead counts grouped by tier/status.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
  /customer/leads/stats:
    get:
      tags: [Customer REST]
      summary: Get aggregate lead stats.
      security:
        - CustomerApiKey: [leads:read]
      responses:
        '200':
          description: Aggregate lead stats.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
  /customer/leads/{leadId}:
    get:
      tags: [Customer REST]
      summary: Get one active lead.
      security:
        - CustomerApiKey: [leads:read]
      parameters:
        - $ref: '#/components/parameters/LeadId'
      responses:
        '200':
          description: Lead detail.
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    $ref: '#/components/schemas/Lead'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
        '404':
          $ref: '#/components/responses/NotFound'
  /customer/leads/{leadId}/engagements:
    get:
      tags: [Customer REST]
      summary: List safe engagement summaries for one lead.
      security:
        - CustomerApiKey: [leads:read]
      parameters:
        - $ref: '#/components/parameters/LeadId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/EngagementTypeFilter'
        - $ref: '#/components/parameters/MonitoredProfileIdFilter'
        - $ref: '#/components/parameters/PostIdFilter'
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
      responses:
        '200':
          description: Engagement page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageEnvelope'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customer/icp:
    get:
      tags: [Customer REST]
      summary: Get active ICP configuration.
      security:
        - CustomerApiKey: [icp:read]
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
  /customer/icp/active:
    get:
      tags: [Customer REST]
      summary: Get active ICP configuration.
      security:
        - CustomerApiKey: [icp:read]
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
  /customer/watchlist/profiles:
    get:
      tags: [Customer REST]
      summary: List watchlist profiles.
      security:
        - CustomerApiKey: [watchlist:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/ProfileTypeFilter'
        - $ref: '#/components/parameters/ProfileTypesFilter'
        - $ref: '#/components/parameters/MonitoredProfileSourceFilter'
        - $ref: '#/components/parameters/SlotKindFilter'
        - $ref: '#/components/parameters/RelationshipLabelFilter'
        - $ref: '#/components/parameters/WatchlistStateFilter'
        - $ref: '#/components/parameters/SearchQueryFilter'
        - $ref: '#/components/parameters/WatchlistSortFilter'
        - $ref: '#/components/parameters/SortDirectionFilter'
      responses:
        '200':
          $ref: '#/components/responses/PageObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
  /customer/watchlist/profiles/{monitoredProfileId}:
    get:
      tags: [Customer REST]
      summary: Get one monitored profile with safe relationship and follower metadata.
      security:
        - CustomerApiKey: [watchlist:read]
      parameters:
        - $ref: '#/components/parameters/MonitoredProfileIdPath'
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
        '404':
          $ref: '#/components/responses/NotFound'
  /customer/watchlist/summary:
    get:
      tags: [Customer REST]
      summary: Get watchlist summary.
      security:
        - CustomerApiKey: [watchlist:read]
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customer/watchlist/recommendations:
    get:
      tags: [Customer REST]
      summary: List watchlist recommendations.
      security:
        - CustomerApiKey: [watchlist:read]
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customer/analytics/dashboard:
    get:
      tags: [Customer REST]
      summary: Get aggregate analytics dashboard.
      security:
        - CustomerApiKey: [analytics:read]
      parameters:
        - $ref: '#/components/parameters/Range'
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customer/analytics/posts:
    get:
      tags: [Customer REST]
      summary: List post analytics, including safe post contentText.
      security:
        - CustomerApiKey: [analytics:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/MonitoredProfileIdFilter'
        - $ref: '#/components/parameters/MonitoredProfileIdsFilter'
        - $ref: '#/components/parameters/ProfileTypeFilter'
        - $ref: '#/components/parameters/RelationshipLabelFilter'
        - $ref: '#/components/parameters/MonitoredProfileSourceFilter'
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
        - $ref: '#/components/parameters/MinIcpMatchPercentFilter'
        - $ref: '#/components/parameters/ContentStatusFilter'
        - $ref: '#/components/parameters/SearchQueryFilter'
        - $ref: '#/components/parameters/ContentSortFilter'
        - $ref: '#/components/parameters/SortDirectionFilter'
      responses:
        '200':
          $ref: '#/components/responses/PageObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customer/analytics/posts/{postId}/summary:
    get:
      tags: [Customer REST]
      summary: Get one post summary, including safe post contentText.
      security:
        - CustomerApiKey: [analytics:read]
      parameters:
        - $ref: '#/components/parameters/PostId'
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '404':
          $ref: '#/components/responses/NotFound'
  /customer/analytics/posts/{postId}/qualified-leads:
    get:
      tags: [Customer REST]
      summary: List qualified leads for one post.
      security:
        - CustomerApiKey: [analytics:read]
      parameters:
        - $ref: '#/components/parameters/PostId'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          $ref: '#/components/responses/PageObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '404':
          $ref: '#/components/responses/NotFound'
  /customer/content-feed:
    get:
      tags: [Customer REST]
      summary: List content feed posts, including safe post contentText.
      security:
        - CustomerApiKey: [content:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/MonitoredProfileIdFilter'
        - $ref: '#/components/parameters/MonitoredProfileIdsFilter'
        - $ref: '#/components/parameters/ProfileTypeFilter'
        - $ref: '#/components/parameters/RelationshipLabelFilter'
        - $ref: '#/components/parameters/MonitoredProfileSourceFilter'
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
        - $ref: '#/components/parameters/MinIcpMatchPercentFilter'
        - $ref: '#/components/parameters/ContentStatusFilter'
        - $ref: '#/components/parameters/SearchQueryFilter'
        - $ref: '#/components/parameters/ContentSortFilter'
        - $ref: '#/components/parameters/SortDirectionFilter'
      responses:
        '200':
          $ref: '#/components/responses/PageObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customer/content/feed:
    get:
      tags: [Customer REST]
      summary: List content feed posts, including safe post contentText.
      security:
        - CustomerApiKey: [content:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/MonitoredProfileIdFilter'
        - $ref: '#/components/parameters/MonitoredProfileIdsFilter'
        - $ref: '#/components/parameters/ProfileTypeFilter'
        - $ref: '#/components/parameters/RelationshipLabelFilter'
        - $ref: '#/components/parameters/MonitoredProfileSourceFilter'
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
        - $ref: '#/components/parameters/MinIcpMatchPercentFilter'
        - $ref: '#/components/parameters/ContentStatusFilter'
        - $ref: '#/components/parameters/SearchQueryFilter'
        - $ref: '#/components/parameters/ContentSortFilter'
        - $ref: '#/components/parameters/SortDirectionFilter'
      responses:
        '200':
          $ref: '#/components/responses/PageObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customer/account-reports:
    get:
      tags: [Customer REST]
      summary: List account summaries derived from active leads.
      security:
        - CustomerApiKey: [leads:read]
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/CompanyNameFilter'
        - $ref: '#/components/parameters/MinIcpMatchPercentFilter'
        - $ref: '#/components/parameters/MaxIcpMatchPercentFilter'
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
        - $ref: '#/components/parameters/SearchQueryFilter'
        - $ref: '#/components/parameters/AccountSortFilter'
        - $ref: '#/components/parameters/SortDirectionFilter'
      responses:
        '200':
          $ref: '#/components/responses/PageObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
  /customer/account-reports/{accountId}:
    get:
      tags: [Customer REST]
      summary: Get one account summary with its top active leads.
      security:
        - CustomerApiKey: [leads:read]
      parameters:
        - $ref: '#/components/parameters/AccountIdPath'
        - $ref: '#/components/parameters/MinIcpMatchPercentFilter'
        - $ref: '#/components/parameters/MaxIcpMatchPercentFilter'
        - $ref: '#/components/parameters/DateFromFilter'
        - $ref: '#/components/parameters/DateToFilter'
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
        '404':
          $ref: '#/components/responses/NotFound'
  /customer/integrations:
    get:
      tags: [Customer REST]
      summary: Get safe integration status.
      security:
        - CustomerApiKey: [integrations:read]
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customer/integrations/status:
    get:
      tags: [Customer REST]
      summary: Get safe integration status.
      security:
        - CustomerApiKey: [integrations:read]
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customer/integrations/leads/{leadId}/delivery:
    get:
      tags: [Customer REST]
      summary: Get lead delivery state.
      security:
        - CustomerApiKey: [integrations:read]
      parameters:
        - $ref: '#/components/parameters/LeadId'
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
  /customer/integrations/lead-delivery-state:
    get:
      tags: [Customer REST]
      summary: Get lead delivery state.
      security:
        - CustomerApiKey: [integrations:read]
      parameters:
        - name: leadId
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
  /customer/sync/status:
    get:
      tags: [Customer REST]
      summary: Get sync status.
      security:
        - CustomerApiKey: [sync:read]
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customer/qualification/runs/latest:
    get:
      tags: [Customer REST]
      summary: Get latest qualification run.
      security:
        - CustomerApiKey: [sync:read]
      responses:
        '200':
          $ref: '#/components/responses/DataObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /audience-analytics/health:
    get:
      tags: [Ordinal Audience Analytics]
      summary: Check Audience Analytics readiness for the key workspace.
      security:
        - CustomerApiKey: [audience_analytics:read]
      responses:
        '200':
          $ref: '#/components/responses/AudienceObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
  /audience-analytics/linkedin-posts:
    get:
      tags: [Ordinal Audience Analytics]
      summary: Get aggregate-only audience analytics for a LinkedIn post.
      security:
        - CustomerApiKey: [audience_analytics:read]
      parameters:
        - name: postUrn
          in: query
          required: true
          description: LinkedIn post URN (`urn:li:activity:...`, `urn:li:share:...`, `urn:li:ugcPost:...`) or a LinkedIn `feed/update` URL containing one of those URNs.
          schema:
            type: string
            maxLength: 1024
          examples:
            activityUrn:
              value: urn:li:activity:123456789
            feedUpdateUrl:
              value: https://www.linkedin.com/feed/update/urn:li:share:123456789/
      responses:
        '200':
          $ref: '#/components/responses/AudienceObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/UnresolvedUrn'
  /audience-analytics/linkedin-posts/find-audience:
    post:
      tags: [Ordinal Audience Analytics]
      summary: Queue on-demand audience discovery for a LinkedIn post.
      description: Starts discovery through the normal traxy post URL qualification pipeline and consumes normal qualification credits only when discovery is actually started.
      security:
        - CustomerApiKey: [audience_analytics:request]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [postUrn]
              additionalProperties: false
              properties:
                postUrn:
                  type: string
                  maxLength: 1024
                  description: LinkedIn post URN or `feed/update` URL containing a LinkedIn post URN.
                idempotencyKey:
                  type: string
                  maxLength: 120
      responses:
        '202':
          $ref: '#/components/responses/AudienceObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/UnresolvedUrn'
        '429':
          $ref: '#/components/responses/RateLimited'
  /audience-analytics/organization:
    get:
      tags: [Ordinal Audience Analytics]
      summary: Get aggregate audience breakdown for the key workspace.
      security:
        - CustomerApiKey: [audience_analytics:read]
      parameters:
        - $ref: '#/components/parameters/Range'
        - name: dimension
          in: query
          schema:
            type: string
            enum: [title, companySize, location, industry]
            default: industry
      responses:
        '200':
          $ref: '#/components/responses/AudienceObject'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientCapability'
  /mcp/oauth/register:
    post:
      tags: [MCP OAuth]
      summary: Register a public MCP OAuth client.
      description: Dynamic Client Registration for public clients. Redirect URIs must be safe loopback URIs or explicitly allowlisted HTTPS origins.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpOAuthClientRegistrationRequest'
      responses:
        '201':
          description: Registered public client metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpOAuthClientRegistrationResponse'
        '400':
          $ref: '#/components/responses/ValidationFailed'
  /mcp/oauth/authorize:
    get:
      tags: [MCP OAuth]
      summary: Start MCP OAuth authorization.
      description: Validates client, redirect URI, resource, scopes, and PKCE challenge, then redirects to the traxy consent screen.
      security: []
      parameters:
        - name: response_type
          in: query
          required: true
          schema:
            type: string
            enum: [code]
        - name: client_id
          in: query
          required: true
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          schema:
            type: string
            format: uri
        - name: code_challenge
          in: query
          required: true
          schema:
            type: string
        - name: code_challenge_method
          in: query
          required: true
          schema:
            type: string
            enum: [S256]
        - name: scope
          in: query
          schema:
            type: string
        - name: resource
          in: query
          schema:
            type: string
            format: uri
        - name: state
          in: query
          schema:
            type: string
      responses:
        '302':
          description: Redirect to traxy consent screen.
        '400':
          $ref: '#/components/responses/ValidationFailed'
  /mcp/oauth/authorize/request:
    get:
      tags: [MCP OAuth]
      summary: Preview a pending MCP OAuth authorization request.
      security:
        - SupabaseUserJwt: []
      parameters:
        - name: request
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Safe consent-screen metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpOAuthAuthorizationPreview'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /mcp/oauth/authorize/complete:
    post:
      tags: [MCP OAuth]
      summary: Approve or cancel MCP OAuth authorization from traxy.
      description: Any active workspace member can approve a request containing only non-sensitive read scopes. The default OAuth grant includes saved contact and profile access, which requires an owner or admin. Scopes that can change workspace data or spend credits also require an owner or admin. Cancellation returns a clean access_denied callback without requiring admin access.
      security:
        - SupabaseUserJwt: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpOAuthAuthorizeCompleteRequest'
      responses:
        '200':
          description: Redirect URL for the MCP client callback.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpOAuthAuthorizeCompleteResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientCapability'
  /mcp/oauth/token:
    post:
      tags: [MCP OAuth]
      summary: Exchange an authorization code or refresh token.
      description: Supports authorization_code with PKCE S256 and refresh_token with rotation.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpOAuthTokenRequest'
      responses:
        '200':
          description: MCP OAuth token response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpOAuthTokenResponse'
        '400':
          $ref: '#/components/responses/ValidationFailed'
        '401':
          $ref: '#/components/responses/McpUnauthorized'
  /mcp/oauth/revoke:
    post:
      tags: [MCP OAuth]
      summary: Revoke an MCP OAuth token.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpOAuthRevokeRequest'
      responses:
        '200':
          description: Token revoke accepted.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
  /mcp:
    get:
      tags: [MCP]
      summary: MCP GET sessions are not enabled in V1.
      security:
        - McpOAuth: []
      responses:
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
    post:
      tags: [MCP]
      summary: Streamable HTTP JSON-RPC endpoint for remote MCP clients.
      security:
        - McpOAuth: []
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: 'application/json, text/event-stream'
        - name: MCP-Protocol-Version
          in: header
          required: false
          schema:
            type: string
            example: '2025-11-25'
          description: Use 2025-11-25 for current clients. 2025-06-18 remains supported for compatibility. The header may be omitted for legacy client compatibility; any supplied value must be supported.
        - name: Origin
          in: header
          schema:
            type: string
          description: Browser origins must match CUSTOMER_API_MCP_ALLOWED_ORIGINS.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpJsonRpcRequest'
      responses:
        '200':
          description: JSON-RPC response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpJsonRpcResponse'
              examples:
                toolsListRepresentative:
                  summary: Representative tools/list response with current MCP annotations.
                  value:
                    jsonrpc: '2.0'
                    id: 2
                    result:
                      tools:
                        - name: traxy_get_workspace_access
                          title: Get workspace access
                          description: Return workspace access, usage, and capabilities for this connection.
                          inputSchema:
                            type: object
                            properties: {}
                            additionalProperties: false
                          annotations:
                            readOnlyHint: true
                          outputSchema:
                            type: object
                            additionalProperties: true
                        - name: traxy_get_mcp_connection_status
                          title: Get MCP connection status
                          description: Return safe diagnostics for the authenticated MCP connection.
                          inputSchema:
                            type: object
                            properties: {}
                            additionalProperties: false
                          annotations:
                            readOnlyHint: true
                          outputSchema:
                            type: object
                            additionalProperties: true
                        - name: traxy_get_agent_status
                          title: Get agent status
                          description: Return safe read-only status for the automated lead-finding agent.
                          inputSchema:
                            type: object
                            properties: {}
                            additionalProperties: false
                          annotations:
                            readOnlyHint: true
                          outputSchema:
                            type: object
                            additionalProperties: true
                        - name: traxy_list_agent_candidates
                          title: List agent candidates
                          description: List candidate summaries for one Agent run, the latest Agent run, or the latest onboarding preview.
                          inputSchema:
                            type: object
                            properties:
                              runId:
                                type: string
                                format: uuid
                              source:
                                type: string
                                enum: [latest_agent_run, latest_onboarding_preview]
                              limit:
                                type: number
                                minimum: 1
                                maximum: 100
                              offset:
                                type: number
                                minimum: 0
                                maximum: 10000
                            additionalProperties: false
                          annotations:
                            readOnlyHint: true
                          outputSchema:
                            type: object
                            additionalProperties: true
                toolArgumentValidationError:
                  summary: Known, authorized tool with model-correctable invalid arguments.
                  value:
                    jsonrpc: '2.0'
                    id: call-1
                    result:
                      content:
                        - type: text
                          text: '{"error":{"code":"validation_failed","message":"Tool traxy_get_lead failed input validation. Fix the arguments and retry.","issues":[{"path":"arguments.leadId","code":"invalid_string","message":"Invalid uuid"}]}}'
                      structuredContent:
                        error:
                          code: validation_failed
                          message: Tool traxy_get_lead failed input validation. Fix the arguments and retry.
                          issues:
                            - path: arguments.leadId
                              code: invalid_string
                              message: Invalid uuid
                      isError: true
        '202':
          description: Notification accepted. The response has no body.
        '400':
          $ref: '#/components/responses/McpBadRequest'
        '401':
          $ref: '#/components/responses/McpUnauthorized'
        '403':
          $ref: '#/components/responses/McpOriginNotAllowed'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    CustomerApiKey:
      type: http
      scheme: bearer
      bearerFormat: trxy_live_<public_id>_<secret>
      description: API key created from Integrations > API. Used for Customer REST and Ordinal Audience Analytics.
    McpOAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Short-lived OAuth access token issued by traxy for the MCP resource.
    SupabaseUserJwt:
      type: http
      scheme: bearer
      bearerFormat: Supabase JWT
      description: Authenticated traxy app session token used by the consent screen.
  parameters:
    Limit:
      name: limit
      in: query
      description: Number of items to return. The default is 50 and the maximum is 100.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    Cursor:
      name: cursor
      in: query
      description: Opaque cursor returned in `page.nextCursor`. Pass it unchanged with the same filters and sort. Incompatible cursors return `validation_failed`.
      schema:
        type: string
        maxLength: 256
    LeadIdFilter:
      name: leadId
      in: query
      schema:
        type: string
        format: uuid
    LeadTierFilter:
      name: tier
      in: query
      schema:
        type: string
        enum: [UNQUALIFIED, NURTURE, QUALIFIED, PRIORITY]
    LeadTiersFilter:
      name: leadTiers
      in: query
      description: Comma-separated lead tiers. Accepts up to four values.
      schema:
        type: string
    LeadDispositionFilter:
      name: disposition
      in: query
      schema:
        type: string
        enum: [ACTIVE, CLIENT, BAD_LEAD]
    LeadDispositionsFilter:
      name: dispositions
      in: query
      description: Comma-separated dispositions. Accepts up to three values. Omitted dispositions default to ACTIVE.
      schema:
        type: string
    MinIcpMatchPercentFilter:
      name: minIcpMatchPercent
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 100
    MaxIcpMatchPercentFilter:
      name: maxIcpMatchPercent
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 100
    MonitoredProfileIdFilter:
      name: monitoredProfileId
      in: query
      schema:
        type: string
        format: uuid
    MonitoredProfileIdsFilter:
      name: monitoredProfileIds
      in: query
      description: Comma-separated monitored profile IDs. Accepts up to 50 IDs.
      schema:
        type: string
    PostIdFilter:
      name: postId
      in: query
      schema:
        type: string
        format: uuid
    EngagementTypeFilter:
      name: engagementType
      in: query
      schema:
        type: string
        enum: [LIKE, COMMENT, REPOST]
    EngagementTypesFilter:
      name: engagementTypes
      in: query
      description: Comma-separated engagement types. Accepts up to three values.
      schema:
        type: string
    OwnerIdFilter:
      name: ownerId
      in: query
      schema:
        type: string
        format: uuid
    OwnerIdsFilter:
      name: ownerIds
      in: query
      description: Comma-separated owner IDs. Accepts up to 50 IDs.
      schema:
        type: string
    DateFromFilter:
      name: dateFrom
      in: query
      description: Inclusive start of the date range.
      schema:
        type: string
        format: date-time
    DateToFilter:
      name: dateTo
      in: query
      description: Inclusive end of the date range.
      schema:
        type: string
        format: date-time
    SearchQueryFilter:
      name: query
      in: query
      schema:
        type: string
        minLength: 1
        maxLength: 160
    CompanyNameFilter:
      name: companyName
      in: query
      schema:
        type: string
        minLength: 1
        maxLength: 160
    CompanyNamesFilter:
      name: companyNames
      in: query
      description: Comma-separated company names. Accepts up to 25 values.
      schema:
        type: string
    LeadOriginFilter:
      name: origin
      in: query
      description: Safe lead origin. `agent` includes automated Agent and preview discovery; `watchlist` includes watched-profile and manual workflows.
      schema:
        type: string
        enum: [agent, watchlist, all]
        default: all
    ProfileTypeFilter:
      name: profileType
      in: query
      schema:
        type: string
        enum: [TEAMMATE, COMPETITOR, INFLUENCER, INVESTOR, CUSTOM]
    ProfileTypesFilter:
      name: profileTypes
      in: query
      description: Comma-separated profile types. Accepts up to five values.
      schema:
        type: string
    MonitoredProfileSourceFilter:
      name: source
      in: query
      schema:
        type: string
        enum: [MEMBER_ONBOARDING, MANUAL_WATCHLIST]
    SlotKindFilter:
      name: slotKind
      in: query
      schema:
        type: string
        enum: [SELF, STANDARD, COMPETITOR]
    RelationshipLabelFilter:
      name: relationshipLabel
      in: query
      schema:
        type: string
        minLength: 1
        maxLength: 80
    WatchlistStateFilter:
      name: state
      in: query
      schema:
        type: string
        enum: [ACTIVE, PAUSED]
    WatchlistSortFilter:
      name: sort
      in: query
      schema:
        type: string
        enum: [createdAt, followers, lastEngagementSyncAt, displayName]
        default: createdAt
    ContentStatusFilter:
      name: status
      in: query
      schema:
        type: string
        enum: [any, qualified, unqualified]
        default: any
    ContentSortFilter:
      name: sort
      in: query
      schema:
        type: string
        enum: [date, engagement, reactions, comments, reposts]
        default: date
    AccountSortFilter:
      name: sort
      in: query
      schema:
        type: string
        enum: [latestSignalAt, leadCount, averageIcpMatchPercent, accountName]
        default: latestSignalAt
    SortDirectionFilter:
      name: sortDirection
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: desc
    Range:
      name: range
      in: query
      schema:
        type: string
        enum: [7d, 30d, 90d]
        default: 30d
    LeadId:
      name: leadId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    PostId:
      name: postId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    MonitoredProfileIdPath:
      name: monitoredProfileId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    AccountIdPath:
      name: accountId
      in: path
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 256
  responses:
    DataObject:
      description: Data envelope.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    PageObject:
      description: Paginated data envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PageEnvelope'
    AudienceObject:
      description: Aggregate-only audience response.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Unauthorized:
      description: Invalid, expired, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    McpUnauthorized:
      description: Invalid, expired, revoked, or wrong-audience MCP OAuth token. Response includes a WWW-Authenticate challenge with resource metadata.
      headers:
        WWW-Authenticate:
          schema:
            type: string
            example: Bearer resource_metadata="https://api.traxy.ai/.well-known/oauth-protected-resource/api/v1/mcp" scope="workspace:read leads:read agent:read"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InsufficientCapability:
      description: Key or OAuth grant lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ValidationFailed:
      description: Request failed boundary validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    McpBadRequest:
      description: MCP transport/header failure or top-level request validation failure.
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/McpJsonRpcResponse'
              - $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: Resource not found for the key workspace.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    UnresolvedUrn:
      description: Malformed or unsupported LinkedIn URN. Valid absent and cross-workspace post URNs use NotFound.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    McpOriginNotAllowed:
      description: Browser Origin is not allowed for MCP.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    MethodNotAllowed:
      description: HTTP method not supported for this endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: Customer API rate limit exceeded. Retry after the delay in the Retry-After header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    McpOAuthClientRegistrationRequest:
      type: object
      additionalProperties: false
      required: [redirect_uris]
      properties:
        client_name:
          type: string
          example: Codex
        redirect_uris:
          type: array
          minItems: 1
          items:
            type: string
            format: uri
          example: ['http://localhost:1455/callback']
        grant_types:
          type: array
          items:
            type: string
            enum: [authorization_code, refresh_token]
        response_types:
          type: array
          items:
            type: string
            enum: [code]
        scope:
          type: string
          description: Space-separated OAuth scopes.
          example: 'workspace:read leads:read agent:read'
        token_endpoint_auth_method:
          type: string
          enum: [none]
          default: none
    McpOAuthClientRegistrationResponse:
      type: object
      required:
        - client_id
        - client_name
        - redirect_uris
        - grant_types
        - response_types
        - token_endpoint_auth_method
        - scope
      properties:
        client_id:
          type: string
          example: mcp_abc123
        client_name:
          type: string
          example: Codex
        redirect_uris:
          type: array
          items:
            type: string
            format: uri
        grant_types:
          type: array
          items:
            type: string
        response_types:
          type: array
          items:
            type: string
        token_endpoint_auth_method:
          type: string
          enum: [none]
        scope:
          type: string
          example: 'workspace:read leads:read analytics:read agent:read'
    McpOAuthAuthorizationPreview:
      type: object
      required: [clientName, requestedScopes, expiresAt, resource]
      properties:
        clientName:
          type: string
          example: Codex
        requestedScopes:
          type: array
          items:
            type: string
            enum:
              - workspace:read
              - leads:read
              - leads:contact_read
              - leads:contact_enrich
              - leads:manage
              - analytics:read
              - icp:read
              - watchlist:read
              - watchlist:manage
              - content:read
              - integrations:read
              - integrations:manage
              - integrations:deliver
              - sync:read
              - agent:read
              - agent:run
              - audience_analytics:read
              - audience_analytics:request
              - post_qualification:manage
        expiresAt:
          type: string
          format: date-time
        resource:
          type: string
          format: uri
          example: https://api.traxy.ai/api/v1/mcp
    McpOAuthAuthorizeCompleteRequest:
      oneOf:
        - type: object
          additionalProperties: false
          required: [requestToken, organizationId, approved]
          properties:
            requestToken:
              type: string
            organizationId:
              type: string
              format: uuid
            approved:
              type: boolean
              enum: [true]
        - type: object
          additionalProperties: false
          required: [requestToken, approved]
          properties:
            requestToken:
              type: string
            organizationId:
              type: string
              format: uuid
            approved:
              type: boolean
              enum: [false]
    McpOAuthAuthorizeCompleteResponse:
      type: object
      required: [redirectUrl]
      properties:
        redirectUrl:
          type: string
          format: uri
          description: Client callback URL. Do not log or send to analytics because it may contain an authorization code.
    McpOAuthTokenRequest:
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - grant_type
            - code
            - redirect_uri
            - client_id
            - code_verifier
          properties:
            grant_type:
              type: string
              enum: [authorization_code]
            code:
              type: string
            redirect_uri:
              type: string
              format: uri
            client_id:
              type: string
            code_verifier:
              type: string
              minLength: 43
              maxLength: 128
            resource:
              type: string
              format: uri
        - type: object
          additionalProperties: false
          required: [grant_type, refresh_token, client_id]
          properties:
            grant_type:
              type: string
              enum: [refresh_token]
            refresh_token:
              type: string
            client_id:
              type: string
            scope:
              type: string
            resource:
              type: string
              format: uri
    McpOAuthTokenResponse:
      type: object
      required: [access_token, token_type, expires_in, refresh_token, scope]
      properties:
        access_token:
          type: string
          description: Short-lived JWT for `/api/v1/mcp`.
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
          example: 900
        refresh_token:
          type: string
          description: Opaque refresh token. Store securely; traxy stores only a hash.
        scope:
          type: string
          example: 'workspace:read leads:read analytics:read agent:read'
    McpOAuthRevokeRequest:
      type: object
      additionalProperties: false
      required: [token]
      properties:
        token:
          type: string
        token_type_hint:
          type: string
          enum: [access_token, refresh_token]
    ErrorEnvelope:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, status, request_id]
          properties:
            code:
              type: string
              example: invalid_api_key
            message:
              type: string
              example: Invalid API key.
            status:
              type: integer
              example: 401
            request_id:
              type: string
    WorkspaceAccess:
      type: object
      required:
        - organizationId
        - dataAccess
        - usage
      properties:
        organizationId:
          type: string
          format: uuid
        dataAccess:
          type: object
          additionalProperties: false
          required:
            - workspace
            - leads
            - leadContactData
            - leadContactEnrichment
            - analytics
            - icp
            - watchlist
            - content
            - integrations
            - sync
            - agent
            - audienceAnalytics
            - audienceDiscovery
          properties:
            workspace:
              type: boolean
            leads:
              type: boolean
            leadContactData:
              type: boolean
            leadContactEnrichment:
              type: boolean
            analytics:
              type: boolean
            icp:
              type: boolean
            watchlist:
              type: boolean
            content:
              type: boolean
            integrations:
              type: boolean
            sync:
              type: boolean
            agent:
              type: boolean
            audienceAnalytics:
              type: boolean
            audienceDiscovery:
              type: boolean
        usage:
          type: object
          additionalProperties: false
          required:
            - apiVisibleLeadCount
            - monitoredProfileCount
          properties:
            apiVisibleLeadCount:
              type: integer
            monitoredProfileCount:
              type: integer
    LeadPage:
      allOf:
        - $ref: '#/components/schemas/PageEnvelope'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Lead'
    Lead:
      type: object
      required:
        - id
        - profile
        - contact
      properties:
        id:
          type: string
          format: uuid
        icpMatchPercent:
          type: integer
          nullable: true
        intentScore:
          type: number
        leadTier:
          type: string
          nullable: true
        profile:
          type: object
          additionalProperties: true
        contact:
          nullable: true
          description: Null unless the key has leads:contact_read.
          type: object
          additionalProperties: true
    PageEnvelope:
      type: object
      required: [data, page]
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: true
        page:
          type: object
          required: [limit, nextCursor]
          properties:
            limit:
              type: integer
            cursor:
              type: string
              nullable: true
            nextCursor:
              type: string
              nullable: true
    McpJsonRpcRequest:
      type: object
      required: [jsonrpc, method]
      additionalProperties: false
      properties:
        jsonrpc:
          type: string
          enum: ['2.0']
        id:
          oneOf:
            - type: string
              nullable: true
            - type: number
        method:
          type: string
          description: MCP request or notification method, including initialize, tools/list, tools/call, and notifications/initialized.
        params:
          type: object
          additionalProperties: true
    McpJsonRpcResponse:
      type: object
      required: [jsonrpc]
      properties:
        jsonrpc:
          type: string
          enum: ['2.0']
        id:
          oneOf:
            - type: string
              nullable: true
            - type: number
        result:
          type: object
          additionalProperties: true
        error:
          type: object
          additionalProperties: true