openapi: 3.2.0
info:
  title: Resume Agent Observations API
  description: Query a candidate's professional profile. Use queryProfile for natural language questions, matchJob to score against a job description, and the GET endpoints for structured profile data.
  version: 1.0.0
servers:
- url: https://agent.yuens.me
tags:
- name: Observations
paths:
  /observations:
    get:
      operationId: listObservations
      summary: Browse the candidate's authored reasoning/premise trail
      description: Returns public-eligible OB1 observations — the dated, authored "why and lessons" notes behind the profile (types observation/idea/task), each with a stable URL for citation. Every item carries an "authored" boolean separating hand-written notes from machine-generated sync/telemetry entries; filter with authored=1 or authored=0. Excludes the git-sync changelog ledger (type=reference) by default; pass type=reference to read it. Private notes are always excluded.
      parameters:
      - name: topic
        in: query
        required: false
        schema:
          type: string
        description: Filter by an OB1 topic tag (case-insensitive)
      - name: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - observation
          - idea
          - task
          - reference
        description: Override the default type filter (observation/idea/task). Use "reference" for the git/changelog ledger.
      - name: since
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Only observations on or after this date (YYYY-MM-DD)
      - name: authored
        in: query
        required: false
        schema:
          type: string
        description: 'Restrict to authored notes or to machine-generated sync/telemetry entries. Truthy: 1, true, yes, or a bare ?authored with no value. Falsy: 0, false, no. Case-insensitive; an unrecognized value is ignored. Omitted returns both classes — the default listing is unchanged. Applied before the limit, so authored=1&limit=25 yields 25 authored notes.'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 25
      responses:
        '200':
          description: A list of public-eligible observations, each individually addressable
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  scope:
                    type: object
                    description: 'The active topic scope: {topic}, {topics}, or {recent:true}'
                  types:
                    type: array
                    items:
                      type: string
                    description: The thought types included (default observation/idea/task, or the explicit ?type)
                  authored:
                    type: boolean
                    description: Echo of the ?authored filter. Present only when the filter was requested — its absence on a filtered request identifies a deployment predating this field.
                  note:
                    type: string
                    description: Human-readable description of what this surface returns
                  observations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        date:
                          type: string
                          format: date
                        type:
                          type: string
                          nullable: true
                        topics:
                          type: array
                          items:
                            type: string
                        content:
                          type: string
                        url:
                          type: string
                          format: uri
                          description: Stable URL for this observation (GET returns the single record)
                        authored:
                          type: boolean
                          description: True for a hand-written note; false for a machine-generated sync/telemetry entry (e.g. a VERSION DRIFT warning).
      tags:
      - Observations