hyreflow-ai .well Known API

openapi: 3.2.0
info:
  title: hyreflow engine (local) .well Known API
  version: 0.1.0
tags:
- name: .well Known
paths:
  /.well-known/openai-apps-challenge:
    get:
      summary: Openai Apps Challenge
      description: 'Domain proof for the OpenAI plugin directory: the portal hands the publisher a token and fetches

        it back from this exact path on the MCP server''s host, as bare text — not JSON, no wrapping. The token

        comes from the environment so rotating it is a config change, not a deploy; unset, the path is a 404

        like any other, so nothing is claimable by accident.'
      operationId: openai_apps_challenge__well_known_openai_apps_challenge_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - .well Known
  /.well-known/oauth-protected-resource/api/v2/mcp:
    get:
      summary: Protected Resource Metadata
      operationId: protected_resource_metadata__well_known_oauth_protected_resource_api_v2_mcp_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - .well Known
  /.well-known/oauth-authorization-server:
    get:
      summary: Authorization Server Metadata
      operationId: authorization_server_metadata__well_known_oauth_authorization_server_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - .well Known
  /.well-known/skills/index.json:
    get:
      summary: Skills Wellknown Index
      description: 'Skill-discovery index for any agent harness, not just our own CLI — same public rationale as

        skills_bundle (no secrets ship in these packages; there''s no bearer yet at discovery time).


        Every entry is consumable BOTH ways, because harnesses split on this and the index can''t know which

        one is reading it:

        * `files` + the per-file route — a consumer that GETs each file as text (Hermes does exactly this:

        it reads `files`, defaults to ["SKILL.md"], and fetches `//`). Note it

        derives that base from the INDEX URL and ignores any `base_url` we publish, so the per-file route

        has to live directly beside this one.

        * `url` + `digest` — one byte-verifiable archive, for a consumer that would rather take the whole

        package in a single request than make ~70 of them.

        Dropping either half silently breaks whichever consumer needed it — an archive-only index leaves

        Hermes 404ing on SKILL.md, and it still LISTS fine (search only reads name+description), so the

        failure shows up at install time, not discovery.


        `$schema` is what selects the parse in a consumer that knows both shapes, so it can''t be added as

        decoration: declaring it routes the reference installer down its single-artifact path, where only

        `name`/`type`/`url`/`digest` are read and the archive is expected to unpack from its root. `version`,

        `base_url`, `files`, `entrypoint` and `documents` ride along as extra keys for the consumers that use

        them (they''re ignored by the artifact path), and every skills_sha-keyed extra stays consistent with the

        digest because both come off the same content hash.'
      operationId: skills_wellknown_index__well_known_skills_index_json_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - .well Known
  /.well-known/skills/archives/{name}.tar.gz:
    get:
      summary: Skills Wellknown Archive
      description: 'Serve one package''s deterministic gzip tarball — see _skill_archive for what keeps this

        byte-identical to the digest index.json advertises. Unknown/non-skill name (incl. any traversal

        shape, which can''t even reach here — no `/` fits {name}) -> 404, never a path outside SKILL_ROOT.'
      operationId: skills_wellknown_archive__well_known_skills_archives__name__tar_gz_get
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - .well Known
  /.well-known/skills/{name}/{rel_path}:
    get:
      summary: Skills Wellknown File
      description: 'One file from one package, as text — the half of the catalog a harness uses when it installs by

        fetching each file rather than an archive (see skills_wellknown_index for who does which).


        Everything served here is inside a package the index already lists publicly, and `{rel_path:path}`

        accepts slashes, so this is the one catalog route where a traversal is expressible. Two independent

        gates: the name must be a real package, and the resolved path must stay inside that package — a

        `..` climb, an absolute path, or a symlink pointing out all fail the second one.'
      operationId: skills_wellknown_file__well_known_skills__name___rel_path__get
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      - name: rel_path
        in: path
        required: true
        schema:
          type: string
          title: Rel Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - .well Known
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer