Scott Ai sync-chat API

openapi: 3.1.0
info:
  title: One-Shot access sync-chat API
  version: 1.0.0
tags:
- name: sync-chat
paths:
  /agent-loop/sync-chat/turns:
    get:
      tags:
      - sync-chat
      summary: List Sync Chat Turns
      description: 'List the caller''s sync-chat thread (renderer-facing).


        Scoped to the authenticated user; oldest first so the UI repaints the

        conversation on reload and chains the next message onto the last.'
      operationId: list_sync_chat_turns
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncChatThreadResponse'
      security:
      - HTTPBearer: []
    post:
      tags:
      - sync-chat
      summary: Create Sync Chat Turn
      description: 'Open or extend the caller''s sync-chat thread.


        Renderer-facing (Stytch session gates the call; the thread is the

        caller''s own). Writes a pending sync_chat_turns row, mints a handoff JWT

        carrying caps=[''sync-chat-turn''] bound to this turn, stores it in Redis,

        and returns the handoff code the renderer forwards to agent-service.

        No workspace or snapshot coupling.'
      operationId: create_sync_chat_turn
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSyncChatTurnRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSyncChatTurnResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /agent-loop/sync-chat/start-review:
    post:
      tags:
      - sync-chat
      summary: Start Sync Chat Review
      description: 'Ensure a post-`scott sync` review turn is in flight, and dispatch it.


        Called by both the CLI (after an upload) and the /sync page (on an empty or

        stale thread), so it is idempotent: if a review turn is already pending or

        streaming at the thread tip, it re-nudges that turn instead of stacking a

        duplicate. A fresh review is only created once the previous one has settled,

        so a later sync reflects the newly uploaded sessions.


        Dispatch is best-effort. The pending row is the durable work item; on a

        missed dispatch reconcile_sync_chat_turns re-dispatches it, so this returns

        200 (the review is queued) rather than 503.'
      operationId: start_sync_chat_review
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSyncChatTurnResponse'
      security:
      - HTTPBearer: []
  /agent-loop/sync-chat/context:
    get:
      tags:
      - sync-chat
      summary: Get Sync Chat Context
      description: "Per-user corpus-digest context for a sync-chat turn (agent-service-facing).\n\nAuthed by the sync-chat-turn JWT. The JWT's user_id scopes the entire\nresponse; request inputs cannot widen it. Returns:\n  - corpus digest: the user's scott-push sessions from the last 14 days\n    with stats and key messages, recency-ordered (newest first, limit 30)\n  - GitHub install state: so the assistant knows whether to nudge\n  - thread ancestry: root to from_turn_id (same as review-chat context)"
      operationId: get_sync_chat_context
      parameters:
      - name: from_turn_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: From Turn Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncChatContextResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent-loop/sync-chat/connected-sources/retrieval-details:
    post:
      tags:
      - sync-chat
      summary: Sync Chat Connected Source Retrieval Details
      description: 'Mint clone + token retrieval details for a sync-chat connected source.


        The agent holds the in-memory ConnectedSource from /context and posts it

        back here to clone the repo mid-turn. Re-resolving from its config/metadata

        only mints a token for a repo the user''s own install already reaches, so no

        persistence or workspace coupling is required (sync-chat is per-user).'
      operationId: sync_chat_connected_source_retrieval_details
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectedSource'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent-loop/sync-chat/sessions/{workspace_id}/transcript:
    get:
      tags:
      - sync-chat
      summary: Get Sync Chat Session Transcript
      description: 'Full transcript of one of the caller''s own push sessions (agent-facing).


        The JWT''s user_id scopes the query; a workspace_id not authored by this

        user returns an empty transcript rather than another user''s turns. This is

        the data plane behind Sync Chat''s read_session_transcript tool.'
      operationId: get_sync_chat_session_transcript
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          title: Workspace Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          description: Maximum number of imported session turns to return, ordered oldest first.
          default: 200
          title: Limit
        description: Maximum number of imported session turns to return, ordered oldest first.
      - name: include_message_deltas
        in: query
        required: false
        schema:
          type: boolean
          description: Include stored replay message_deltas alongside user/assistant text.
          default: true
          title: Include Message Deltas
        description: Include stored replay message_deltas alongside user/assistant text.
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncChatTranscriptResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent-loop/sync-chat/turns/{turn_id}:
    patch:
      tags:
      - sync-chat
      summary: Update Sync Chat Turn
      description: 'Persist agent output onto a sync-chat turn (agent-service-facing).


        The JWT is bound to this turn_id (caps=[''sync-chat-turn'']); the service

        cross-checks user ownership before writing. Same body shape as the

        contributor PATCH /turns/{id}. No cursor advance: sync-chat is off the DAG.'
      operationId: update_sync_chat_turn
      parameters:
      - name: turn_id
        in: path
        required: true
        schema:
          type: string
          title: Turn Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTurnRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Update Sync Chat Turn
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent-loop/sync-chat/pin:
    post:
      tags:
      - sync-chat
      summary: Sync Chat Pin Workspace
      description: 'Pin or unpin one of the caller''s own push planspaces (agent-service-facing).


        Both endpoints are strictly user-scoped: a sync-chat turn can pin or write up

        ONLY the caller''s own push planspaces. A workspace_id that is not one of the

        caller''s own scott_push_artifacts (matched on captured_by_user_id == user_id)

        returns 403.


        Authed by the sync-chat-turn JWT; the JWT''s user_id is the only identity that

        matters. The request body cannot widen scope.'
      operationId: sync_chat_pin_workspace
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncChatPinRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Sync Chat Pin Workspace
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agent-loop/sync-chat/write-up:
    post:
      tags:
      - sync-chat
      summary: Sync Chat Write Up Workspace
      description: 'Trigger a tailored write-up on one of the caller''s own push planspaces.


        Both endpoints are strictly user-scoped: a sync-chat turn can pin or write up

        ONLY the caller''s own push planspaces. A workspace_id that is not one of the

        caller''s own scott_push_artifacts (matched on captured_by_user_id == user_id)

        returns 403.


        Appends a single pending synthesis turn off the planspace''s scott-push chain

        tip (the planspace was bulk-uploaded with synthesize=false), then dispatches

        it to agent-service after commit, the same way push-ingest synthesis fans out.'
      operationId: sync_chat_write_up_workspace
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SyncChatWriteUpRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Sync Chat Write Up Workspace
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    UploadedFileSourceConfig:
      properties:
        file_id:
          type: string
          title: File Id
      type: object
      required:
      - file_id
      title: UploadedFileSourceConfig
      description: Configuration for an uploaded file source
    RetrievalKind:
      type: string
      enum:
      - git
      - file
      title: RetrievalKind
      description: Kind of retrieval method (git clone, file download, etc.)
    CreateSyncChatTurnResponse:
      properties:
        turn_id:
          type: string
          title: Turn Id
        handoff_code:
          type: string
          title: Handoff Code
          description: Single-use code redeemable at /agent-loop/internal/agent-token/redeem for the sync-chat agent-svc JWT (caps=['sync-chat-turn']) bound to this turn. 60s TTL.
      type: object
      required:
      - turn_id
      - handoff_code
      title: CreateSyncChatTurnResponse
    SyncChatContextResponse:
      properties:
        digest:
          items:
            $ref: '#/components/schemas/SyncChatDigestSession'
          type: array
          title: Digest
        github_installs:
          items:
            $ref: '#/components/schemas/SyncChatGitHubInstall'
          type: array
          title: Github Installs
        connected_sources:
          items:
            $ref: '#/components/schemas/ConnectedSource'
          type: array
          title: Connected Sources
          default: []
        connected_sources_fingerprint:
          anyOf:
          - type: string
          - type: 'null'
          title: Connected Sources Fingerprint
        turns:
          items:
            $ref: '#/components/schemas/SyncChatContextTurn'
          type: array
          title: Turns
      type: object
      required:
      - digest
      - github_installs
      - turns
      title: SyncChatContextResponse
      description: 'Per-user context for a sync-chat turn: corpus digest, GitHub install

        state, usable connected sources, and this user''s thread ancestry.'
    UpdateTurnRequest:
      properties:
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        assistant_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Assistant Text
        tool_calls:
          anyOf:
          - {}
          - type: 'null'
          title: Tool Calls
        message_deltas:
          anyOf:
          - {}
          - type: 'null'
          title: Message Deltas
        usage:
          anyOf:
          - {}
          - type: 'null'
          title: Usage
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      type: object
      title: UpdateTurnRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SyncChatContextTurn:
      properties:
        id:
          type: string
          title: Id
        parent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Id
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        user_message:
          anyOf:
          - type: string
          - type: 'null'
          title: User Message
        assistant_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Assistant Text
        message_deltas:
          anyOf:
          - {}
          - type: 'null'
          title: Message Deltas
        usage:
          anyOf:
          - {}
          - type: 'null'
          title: Usage
      type: object
      required:
      - id
      - parent_id
      - user_message
      - assistant_text
      title: SyncChatContextTurn
      description: Sync-chat thread turn for agent hydration.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UploadedFileSourceMetadata:
      properties:
        filename:
          type: string
          title: Filename
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
        size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size Bytes
      type: object
      required:
      - filename
      title: UploadedFileSourceMetadata
      description: Metadata for an uploaded file source
    SourceVisibility:
      type: string
      enum:
      - private
      - public
      title: SourceVisibility
      description: Visibility level of a source
    SyncChatWriteUpRequest:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        intent:
          anyOf:
          - type: string
          - type: 'null'
          title: Intent
      type: object
      required:
      - workspace_id
      title: SyncChatWriteUpRequest
      description: Agent-service body to write up (synthesize) one of the caller's planspaces.
    SyncChatThreadTurn:
      properties:
        id:
          type: string
          title: Id
        parent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Id
        status:
          type: string
          title: Status
        user_message:
          anyOf:
          - type: string
          - type: 'null'
          title: User Message
        assistant_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Assistant Text
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - parent_id
      - status
      - user_message
      - assistant_text
      - created_at
      title: SyncChatThreadTurn
      description: One persisted sync-chat turn for renderer rehydration.
    CreateSyncChatTurnRequest:
      properties:
        parent_turn_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Turn Id
        user_message:
          anyOf:
          - type: string
          - type: 'null'
          title: User Message
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        connected_sources:
          anyOf:
          - items:
              $ref: '#/components/schemas/ConnectedSourceSelection'
            type: array
          - type: 'null'
          title: Connected Sources
      type: object
      title: CreateSyncChatTurnRequest
      description: 'Renderer body for opening/extending the caller''s sync-chat thread.


        parent_turn_id is null for the first message, the prior turn''s id

        thereafter. id lets the client supply the turn id (optimistic UI).'
    SyncChatTranscriptResponse:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        turns:
          items:
            $ref: '#/components/schemas/SyncChatTranscriptTurn'
          type: array
          title: Turns
      type: object
      required:
      - workspace_id
      - turns
      title: SyncChatTranscriptResponse
      description: Full ordered transcript of one of the caller's push sessions.
    RetrievalResult:
      properties:
        adapter:
          $ref: '#/components/schemas/AdapterType'
        retrieval:
          anyOf:
          - $ref: '#/components/schemas/GitRetrievalDetails'
          - $ref: '#/components/schemas/FileRetrievalDetails'
          title: Retrieval
      type: object
      required:
      - adapter
      - retrieval
      title: RetrievalResult
      description: Result of retrieving a source (how to actually fetch it)
    GitHubSourceMetadata:
      properties:
        installation_id:
          type: integer
          title: Installation Id
        commit_sha:
          type: string
          title: Commit Sha
      type: object
      required:
      - installation_id
      - commit_sha
      title: GitHubSourceMetadata
      description: Metadata for a GitHub source
    SyncChatPinRequest:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        pinned:
          type: boolean
          title: Pinned
          default: true
      type: object
      required:
      - workspace_id
      title: SyncChatPinRequest
      description: Agent-service body to pin one of the caller's push planspaces.
    SyncChatTranscriptTurn:
      properties:
        turn_id:
          type: string
          title: Turn Id
        parent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Id
        created_at:
          type: string
          format: date-time
          title: Created At
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
        status:
          type: string
          title: Status
        user_message:
          anyOf:
          - type: string
          - type: 'null'
          title: User Message
        assistant_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Assistant Text
        message_deltas:
          anyOf:
          - {}
          - type: 'null'
          title: Message Deltas
          description: Stored replay messages for this turn when include_message_deltas=true.
      type: object
      required:
      - turn_id
      - created_at
      - status
      - user_message
      - assistant_text
      title: SyncChatTranscriptTurn
      description: One turn of a push session's full transcript, in order.
    SyncChatGitHubInstall:
      properties:
        installation_id:
          type: integer
          title: Installation Id
        account_login:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Login
      type: object
      required:
      - installation_id
      title: SyncChatGitHubInstall
    ConnectedSourceSelection:
      properties:
        adapter:
          $ref: '#/components/schemas/AdapterType'
        selection:
          anyOf:
          - $ref: '#/components/schemas/GitHubSourceSelection'
          - $ref: '#/components/schemas/SlackSourceSelection'
          - $ref: '#/components/schemas/UploadedFileSourceSelection'
          title: Selection
      type: object
      required:
      - adapter
      - selection
      title: ConnectedSourceSelection
    UploadedFileSourceSelection:
      properties:
        file_id:
          type: string
          title: File Id
        visibility:
          $ref: '#/components/schemas/SourceVisibility'
          default: private
      type: object
      required:
      - file_id
      title: UploadedFileSourceSelection
      description: User's selection when connecting an uploaded file source
    ConnectedSource:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        linked_by_user_id:
          type: string
          title: Linked By User Id
        adapter:
          $ref: '#/components/schemas/AdapterType'
        visibility:
          $ref: '#/components/schemas/SourceVisibility'
          default: private
        config:
          anyOf:
          - $ref: '#/components/schemas/GitHubSourceConfig'
          - $ref: '#/components/schemas/SlackSourceConfig'
          - $ref: '#/components/schemas/UploadedFileSourceConfig'
          title: Config
        metadata:
          anyOf:
          - $ref: '#/components/schemas/GitHubSourceMetadata'
          - $ref: '#/components/schemas/SlackSourceMetadata'
          - $ref: '#/components/schemas/UploadedFileSourceMetadata'
          title: Metadata
      type: object
      required:
      - linked_by_user_id
      - adapter
      - config
      - metadata
      title: ConnectedSource
    FileRetrievalDetails:
      properties:
        kind:
          $ref: '#/components/schemas/RetrievalKind'
          default: file
        download_url:
          type: string
          title: Download Url
        filename:
          type: string
          title: Filename
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
        size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size Bytes
      type: object
      required:
      - download_url
      - filename
      title: FileRetrievalDetails
      description: Details for retrieving source via file download
    GitHubSourceSelection:
      properties:
        repo:
          type: string
          title: Repo
        branch:
          type: string
          title: Branch
      type: object
      required:
      - repo
      - branch
      title: GitHubSourceSelection
      description: User's selection when connecting a GitHub source
    SlackSourceMetadata:
      properties:
        team_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Name
        channel_name:
          type: string
          title: Channel Name
        is_private:
          type: boolean
          title: Is Private
          default: false
      type: object
      required:
      - channel_name
      title: SlackSourceMetadata
      description: Metadata for a Slack source
    SyncChatThreadResponse:
      properties:
        turns:
          items:
            $ref: '#/components/schemas/SyncChatThreadTurn'
          type: array
          title: Turns
      type: object
      required:
      - turns
      title: SyncChatThreadResponse
      description: The caller's full sync-chat thread, oldest first.
    GitHubSourceConfig:
      properties:
        repo:
          type: string
          title: Repo
        branch:
          type: string
          title: Branch
      type: object
      required:
      - repo
      - branch
      title: GitHubSourceConfig
      description: Configuration for a GitHub source
    SlackSourceConfig:
      properties:
        slack_team_id:
          type: string
          title: Slack Team Id
        channel_id:
          type: string
          title: Channel Id
      type: object
      required:
      - slack_team_id
      - channel_id
      title: SlackSourceConfig
      description: Configuration for a Slack source
    GitRetrievalDetails:
      properties:
        kind:
          $ref: '#/components/schemas/RetrievalKind'
          default: git
        clone_url:
          type: string
          title: Clone Url
        token:
          type: string
          title: Token
        repo:
          type: string
          title: Repo
        branch:
          type: string
          title: Branch
        commit_sha:
          type: string
          title: Commit Sha
      type: object
      required:
      - clone_url
      - token
      - repo
      - branch
      - commit_sha
      title: GitRetrievalDetails
      description: Details for retrieving source via git clone
    SlackSourceSelection:
      properties:
        slack_team_id:
          type: string
          title: Slack Team Id
        channel_id:
          type: string
          title: Channel Id
      type: object
      required:
      - slack_team_id
      - channel_id
      title: SlackSourceSelection
      description: User's selection when connecting a Slack source
    SyncChatDigestSession:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        name:
          type: string
          title: Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        stats:
          anyOf:
          - {}
          - type: 'null'
          title: Stats
        git_remote:
          anyOf:
          - type: string
          - type: 'null'
          title: Git Remote
        git_branch:
          anyOf:
          - type: string
          - type: 'null'
          title: Git Branch
        captured_at:
          type: string
          format: date-time
          title: Captured At
        key_messages:
          items:
            type: string
          type: array
          title: Key Messages
          default: []
      type: object
      required:
      - workspace_id
      - name
      - captured_at
      title: SyncChatDigestSession
      description: One scott-push session row for the corpus digest.
    AdapterType:
      type: string
      enum:
      - github
      - slack
      - uploaded_file
      title: AdapterType
      description: Type of source adapter (github, uploaded_file, etc.)
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer