openapi: 3.1.0
info:
  title: SalesBreaker Execution API
  version: 0.0.1
  summary: Limited Partner Access API contract for SalesBreaker execution workflows.
  description: |
    SalesBreaker provides sales action execution infrastructure for AI agents, CRMs, and revenue automation platforms.

    This v0 document is a limited partner access contract stub under /api/execution/v0. It describes non-destructive workflow surfaces first: precheck, dry-run, status, and result retrieval.

    Public self-service API keys are not available at this time. Write-capable execution is partner-limited and is not described as a public self-service capability in this v0 stub.
servers:
  - url: https://salesbreaker.jp
    description: SalesBreaker production control plane
security:
  - PartnerBearerAuth: []
tags:
  - name: Executions
    description: Governed sales action execution workflow endpoints.
paths:
  /api/execution/v0/precheck:
    post:
      tags:
        - Executions
      operationId: createExecutionPrecheck
      summary: Precheck a sales action target before execution.
      description: |
        Performs a non-destructive precheck for a target sales action. This endpoint is intended to help partners and AI agents determine whether a target is eligible for a later dry-run or execution workflow.
      x-salesbreaker-access: limited_partner_access
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrecheckRequest'
      responses:
        '200':
          description: Precheck completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrecheckResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/execution/v0/executions/dry-run:
    post:
      tags:
        - Executions
      operationId: createExecutionDryRun
      summary: Create a non-destructive execution plan.
      description: |
        Creates a dry-run execution plan without performing a write-capable sales action. Dry-run output can be reviewed by partners, AI agents, and the SalesBreaker control plane before actual execution is considered.
      x-salesbreaker-access: limited_partner_access
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DryRunRequest'
      responses:
        '202':
          description: Dry-run request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DryRunAcceptedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/execution/v0/executions/{execution_id}:
    get:
      tags:
        - Executions
      operationId: getExecutionStatus
      summary: Retrieve execution workflow status.
      description: Returns the current status of a precheck, dry-run, or partner-approved execution workflow.
      x-salesbreaker-access: limited_partner_access
      parameters:
        - $ref: '#/components/parameters/ExecutionId'
      responses:
        '200':
          description: Current execution status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/execution/v0/results/{result_id}:
    get:
      tags:
        - Executions
      operationId: getExecutionResult
      summary: Retrieve execution workflow result.
      description: Returns a partner-safe result object for a completed workflow.
      x-salesbreaker-access: limited_partner_access
      parameters:
        - $ref: '#/components/parameters/ResultId'
      responses:
        '200':
          description: Execution result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExecutionResultResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    PartnerBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: partner-token
      description: Limited partner bearer token. Public self-service API keys are not available.
  parameters:
    ExecutionId:
      name: execution_id
      in: path
      required: true
      schema:
        type: string
      description: SalesBreaker execution workflow identifier.
    ResultId:
      name: result_id
      in: path
      required: true
      schema:
        type: string
      description: SalesBreaker execution result identifier.
  responses:
    Unauthorized:
      description: Missing or invalid partner credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: The partner is not allowed to access this workflow or capability.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Execution workflow not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit or partner execution capacity limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    PrecheckRequest:
      type: object
      additionalProperties: false
      required:
        - target
        - requested_action
      properties:
        partner_reference_id:
          type: string
          description: Partner-side idempotency or trace reference.
        requested_action:
          type: string
          enum:
            - form_submission_precheck
            - sales_target_validation
        target:
          $ref: '#/components/schemas/SalesTarget'
        metadata:
          type: object
          additionalProperties: true
    PrecheckResponse:
      type: object
      additionalProperties: false
      required:
        - precheck_id
        - status
        - eligible_for_dry_run
      properties:
        precheck_id:
          type: string
        status:
          type: string
          enum:
            - accepted
            - completed
            - rejected
        eligible_for_dry_run:
          type: boolean
        reasons:
          type: array
          items:
            type: string
        warnings:
          type: array
          items:
            type: string
    DryRunRequest:
      type: object
      additionalProperties: false
      required:
        - target
        - requested_action
      properties:
        partner_reference_id:
          type: string
        precheck_id:
          type: string
        requested_action:
          type: string
          enum:
            - form_submission_dry_run
        target:
          $ref: '#/components/schemas/SalesTarget'
        message_profile:
          type: object
          additionalProperties: true
          description: Partner-safe message or campaign metadata. Do not include secrets.
        metadata:
          type: object
          additionalProperties: true
    DryRunAcceptedResponse:
      type: object
      additionalProperties: false
      required:
        - execution_id
        - status
      properties:
        execution_id:
          type: string
        status:
          type: string
          enum:
            - accepted
            - processing
        status_url:
          type: string
          format: uri
        result_url:
          type: string
          format: uri
    ExecutionStatusResponse:
      type: object
      additionalProperties: false
      required:
        - execution_id
        - status
      properties:
        execution_id:
          type: string
        status:
          type: string
          enum:
            - accepted
            - processing
            - completed
            - failed
            - rejected
            - expired
        mode:
          type: string
          enum:
            - precheck
            - dry_run
            - partner_execution
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        progress:
          type: object
          additionalProperties: true
    ExecutionResultResponse:
      type: object
      additionalProperties: false
      required:
        - execution_id
        - status
        - result
      properties:
        execution_id:
          type: string
        status:
          type: string
          enum:
            - completed
            - failed
            - rejected
            - expired
        result:
          type: object
          additionalProperties: true
          description: Partner-safe normalized result. The exact fields depend on the approved integration scope.
        audit:
          type: object
          additionalProperties: true
    SalesTarget:
      type: object
      additionalProperties: false
      properties:
        company_name:
          type: string
        website_url:
          type: string
          format: uri
        contact_url:
          type: string
          format: uri
        salesbreaker_target_id:
          type: string
        partner_target_id:
          type: string
        country:
          type: string
          default: JP
      anyOf:
        - required:
            - website_url
        - required:
            - contact_url
        - required:
            - salesbreaker_target_id
        - required:
            - partner_target_id
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
        message:
          type: string
        request_id:
          type: string
