Goodeye Templates API

openapi: 3.2.0
info:
  title: Goodeye Templates API
  version: 0.1.0
servers:
- url: /v1
tags:
- name: Templates
paths:
  /templates:
    get:
      summary: List Templates Route
      description: Browse the public template catalog.
      operationId: list_templates_route_templates_get
      parameters:
      - name: filter
        in: query
        required: false
        schema:
          enum:
          - mine
          - all
          type: string
          default: all
          title: Filter
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: include_archived
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Archived
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response List Templates Route Templates Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
    post:
      summary: Publish Template Version Route
      description: 'Publish a skill as a new template version.


        Bundle a ``demo/README.md`` writeup with images referenced by relative path

        inside ``demo/`` to render a visual demo on the public template page.


        Publishing makes the template''s verifier definitions public: anyone who

        views the template (including anonymous readers) can read each verifier''s

        criterion and calibration examples. Publishing is hard-blocked

        (``SafetyVerificationFailed``) if a verifier definition contains a secret or

        credential, and flagged if it appears to contain private data. When the

        template references verifiers, the response includes a

        ``verifier_exposure_notice`` restating this.


        ``SafetyVerificationFailed`` (422) and ``SafetyVerificationRuntimeError``

        (503) propagate to the app-level ``GoodeyeError`` handler which

        serializes them via ``to_wire``.'
      operationId: publish_template_version_route_templates_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishTemplateVersionInput'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Publish Template Version Route Templates Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/search:
    post:
      summary: Search Templates Route
      description: Search the public template catalog by natural-language query.
      operationId: search_templates_route_templates_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchTemplatesInput'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Search Templates Route Templates Search Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/fork:
    post:
      summary: Fork Template Route
      description: Copy a public template into your own private skill.
      operationId: fork_template_route_templates_fork_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForkTemplateInput'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Fork Template Route Templates Fork Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/{template_identifier}/versions/{version}:
    delete:
      summary: Unpublish Template Version Route
      description: 'Unpublish a template version to stop showing it to readers (distinct from

        deprecate and permanent delete).'
      operationId: unpublish_template_version_route_templates__template_identifier__versions__version__delete
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      - name: version
        in: path
        required: true
        schema:
          type: integer
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Unpublish Template Version Route Templates  Template Identifier  Versions  Version  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/{template_identifier}/versions/{version}/permanent:
    delete:
      summary: Delete Template Version Route
      description: 'Permanently and immediately erase a single template version.


        This is permanent: the version row, all its attached files, all version

        verification records, and any content no longer referenced by any

        surviving version or skill version are removed from the live system at

        once. There is no recovery path. Use ``POST .../archive`` if you want a

        reversible alternative for the whole template.


        Encrypted backups age out within the platform''s standard retention window

        (up to three months), so the data is not instantly erased from all systems

        everywhere, but it is no longer accessible through any product surface

        after this call.


        Serving gate: the version must be unpublished first

        (``DELETE .../versions/{version}``). A still-published version cannot be

        permanently deleted because it is currently served to readers. Use

        ``DELETE /v1/templates/{template_ref}`` to remove the entire template at

        once.


        Version numbers remain monotonic with a gap where the erased version was.

        Surviving versions are not renumbered.


        Returns 200 with ``{template_id, version, deleted: true}``.'
      operationId: delete_template_version_route_templates__template_identifier__versions__version__permanent_delete
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      - name: version
        in: path
        required: true
        schema:
          type: integer
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Delete Template Version Route Templates  Template Identifier  Versions  Version  Permanent Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/{template_identifier}/versions/{version}/deprecate:
    post:
      summary: Deprecate Template Version Route
      description: 'Mark a template version as deprecated without hiding it.


        Distinct from ``DELETE /v1/templates/{template_identifier}/versions/{version}``

        (unpublish): deprecate is a soft signal, unpublish is the hide path.'
      operationId: deprecate_template_version_route_templates__template_identifier__versions__version__deprecate_post
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      - name: version
        in: path
        required: true
        schema:
          type: integer
          title: Version
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeprecateTemplateVersionInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Deprecate Template Version Route Templates  Template Identifier  Versions  Version  Deprecate Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/{template_identifier}/safety-check:
    post:
      summary: Check Template Safety Route
      description: 'Check a published template version for embedded secrets or private data.


        Auth is optional: anonymous callers bill against the per-IP-hash

        anonymous grant via the metering chokepoint.


        Fields longer than the safety check''s input limit are truncated for this

        scan and flagged in the response (``truncated`` plus ``truncated_fields``);

        genuinely invalid input returns 400 ``validation_error``.'
      operationId: check_template_safety_route_templates__template_identifier__safety_check_post
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Version
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Check Template Safety Route Templates  Template Identifier  Safety Check Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/{template_identifier}/transfer-ownership:
    post:
      summary: Transfer Template Ownership Route
      description: Transfer template ownership to another Goodeye user. Owner only.
      operationId: transfer_template_ownership_route_templates__template_identifier__transfer_ownership_post
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TransferTemplateOwnershipInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Transfer Template Ownership Route Templates  Template Identifier  Transfer Ownership Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/{template_identifier}/archive:
    post:
      summary: Archive Template Route
      description: 'Archive a template owned by the caller.


        Body is optional (``{archive_reason}``). Archiving keeps the slug

        occupied and hides the template from public listing. Forks pinned at

        this template keep working.'
      operationId: archive_template_route_templates__template_identifier__archive_post
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/ArchiveTemplateInput'
              - type: 'null'
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Archive Template Route Templates  Template Identifier  Archive Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/{template_identifier}/unarchive:
    post:
      summary: Unarchive Template Route
      description: Restore an archived template. Owner only. Idempotent on live templates.
      operationId: unarchive_template_route_templates__template_identifier__unarchive_post
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Unarchive Template Route Templates  Template Identifier  Unarchive Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/{template_identifier}/files:
    head:
      summary: Get Template File Route
      description: 'Fetch a single file from a template version''s file tree.


        ``path`` must match a row in the template''s file manifest (use

        ``get_template`` to see the manifest). ``SKILL.md`` returns the template

        body. Text files return the decoded string in ``content``. Small binary

        files return base64-encoded bytes in ``content_base64``. Binary files over

        the size limit return metadata and an ``error`` field with no inline bytes.


        Pass ``format=raw`` to receive the file''s raw bytes instead of the JSON

        envelope. This is the path public template pages use to render demo images:

        a validated image is served with its pinned image type, anything else is

        served as a generic download attachment, and every raw response carries

        hardening headers so a file can never execute as an active document in a

        browser. Pair ``format=raw`` with ``sha256`` so the URL is content

        addressed: a republished or removed file no longer resolves at a stale

        address. The default (no ``format``) JSON response is unchanged.


        Anonymous callers may fetch files from live (published) template versions.

        Once a version is unpublished, anonymous reads are denied immediately; the

        liveness check is evaluated per read inside the same transaction, including

        for ``format=raw``.


        When ``path`` is omitted this is not a file request: the greedy ``:path``

        segment swallowed a template whose slug is literally ``files`` (an

        ``@handle/files`` URL), so fall through to ordinary template resolution on

        the reconstructed identifier. Publishing a new template with that slug is

        rejected up front, but legacy templates created before this route existed

        must still resolve here. (Per-file fetches against such a legacy template

        cannot be disambiguated from this route and are not supported, but those

        rows predate sibling files so their only file is the synthesized SKILL.md,

        which the no-path body resolution already returns.)'
      operationId: get_template_file_route_templates__template_identifier__files_head
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      - name: path
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Relative path of the file within the template's file tree
          title: Path
        description: Relative path of the file within the template's file tree
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Version
      - name: format
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Set to 'raw' to return the file's raw bytes (used to render images on public template pages). Omit for the default structured JSON response.
          title: Format
        description: Set to 'raw' to return the file's raw bytes (used to render images on public template pages). Omit for the default structured JSON response.
      - name: sha256
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Content address of the expected file. When provided, the file is resolved by path and then confirmed to match this value; a stale or mismatched address returns not found.
          title: Sha256
        description: Content address of the expected file. When provided, the file is resolved by path and then confirmed to match this value; a stale or mismatched address returns not found.
      - name: accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
          title: Accept
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
    get:
      summary: Get Template File Route
      description: 'Fetch a single file from a template version''s file tree.


        ``path`` must match a row in the template''s file manifest (use

        ``get_template`` to see the manifest). ``SKILL.md`` returns the template

        body. Text files return the decoded string in ``content``. Small binary

        files return base64-encoded bytes in ``content_base64``. Binary files over

        the size limit return metadata and an ``error`` field with no inline bytes.


        Pass ``format=raw`` to receive the file''s raw bytes instead of the JSON

        envelope. This is the path public template pages use to render demo images:

        a validated image is served with its pinned image type, anything else is

        served as a generic download attachment, and every raw response carries

        hardening headers so a file can never execute as an active document in a

        browser. Pair ``format=raw`` with ``sha256`` so the URL is content

        addressed: a republished or removed file no longer resolves at a stale

        address. The default (no ``format``) JSON response is unchanged.


        Anonymous callers may fetch files from live (published) template versions.

        Once a version is unpublished, anonymous reads are denied immediately; the

        liveness check is evaluated per read inside the same transaction, including

        for ``format=raw``.


        When ``path`` is omitted this is not a file request: the greedy ``:path``

        segment swallowed a template whose slug is literally ``files`` (an

        ``@handle/files`` URL), so fall through to ordinary template resolution on

        the reconstructed identifier. Publishing a new template with that slug is

        rejected up front, but legacy templates created before this route existed

        must still resolve here. (Per-file fetches against such a legacy template

        cannot be disambiguated from this route and are not supported, but those

        rows predate sibling files so their only file is the synthesized SKILL.md,

        which the no-path body resolution already returns.)'
      operationId: getTemplatesByTemplateIdentifierFiles
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      - name: path
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Relative path of the file within the template's file tree
          title: Path
        description: Relative path of the file within the template's file tree
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Version
      - name: format
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Set to 'raw' to return the file's raw bytes (used to render images on public template pages). Omit for the default structured JSON response.
          title: Format
        description: Set to 'raw' to return the file's raw bytes (used to render images on public template pages). Omit for the default structured JSON response.
      - name: sha256
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Content address of the expected file. When provided, the file is resolved by path and then confirmed to match this value; a stale or mismatched address returns not found.
          title: Sha256
        description: Content address of the expected file. When provided, the file is resolved by path and then confirmed to match this value; a stale or mismatched address returns not found.
      - name: accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
          title: Accept
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
      x-operation-id-source: normalized
      x-operation-id-original: get_template_file_route_templates__template_identifier__files_head
  /templates/{template_identifier}:
    delete:
      summary: Delete Template Route
      description: 'Permanently and immediately erase a template you own.


        This is permanent: the template, all its versions, all attached files,

        and all version verification records are removed from the live system at

        once. There is no recovery path. Use POST .../archive if you want a

        reversible alternative.


        Encrypted backups age out within the platform''s standard retention window

        (up to three months), so the data is not instantly erased from all systems

        everywhere, but it is no longer accessible through any product surface

        after this call.


        Serving gate: if the template is not archived AND has at least one

        published version (unpublished_at IS NULL), deletion is refused with 409.

        Unpublish the relevant version(s) or archive the template first.


        Fork severing: forks keep their own content; their parent pointer is set

        to null. lookup_fork_lineage reports the source as permanently deleted.


        Returns 200 with ``{template_id, slug, deleted: true}``.'
      operationId: delete_template_route_templates__template_identifier__delete
      parameters:
      - name: template_identifier
        in: path
        required: true
        schema:
          type: string
          title: Template Identifier
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Delete Template Route Templates  Template Identifier  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
  /templates/{identifier}:
    get:
      summary: Get Template Route
      description: Read a public template to run or fork it.
      operationId: get_template_route_templates__identifier__get
      parameters:
      - name: identifier
        in: path
        required: true
        schema:
          type: string
          title: Identifier
      - name: version
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
          - type: 'null'
          title: Version
      - name: accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
          title: Accept
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Templates
components:
  schemas:
    ArchiveTemplateInput:
      properties:
        archive_reason:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Archive Reason
      type: object
      title: ArchiveTemplateInput
      description: 'Optional body for ``POST /v1/templates/{template_identifier}/archive``.


        ``archive_reason`` is a short human-readable note stored on

        ``templates.archive_reason``. Empty body is accepted (FastAPI passes

        ``None`` to the route, which then constructs a default).'
    DeprecateTemplateVersionInput:
      properties:
        message:
          type: string
          maxLength: 1000
          minLength: 1
          title: Message
      type: object
      required:
      - message
      title: DeprecateTemplateVersionInput
      description: 'Input for ``POST /v1/templates/{template_identifier}/versions/{version}/deprecate``.


        ``message`` is required and last-write-wins on

        ``template_versions.deprecation_message``.'
    SearchTemplatesInput:
      properties:
        query:
          type: string
          minLength: 1
          title: Query
          description: Natural-language description of the template you are looking for.
        filter:
          type: string
          enum:
          - mine
          - all
          title: Filter
          description: 'Which templates to search: ''mine'' for ones you published, or ''all'' for the public catalog.'
          default: all
        limit:
          type: integer
          maximum: 10.0
          minimum: 1.0
          title: Limit
          description: Maximum number of ranked results to return (1 to 10).
          default: 5
      type: object
      required:
      - query
      title: SearchTemplatesInput
      description: Natural-language search request over public or owned templates.
    TransferTemplateOwnershipInput:
      properties:
        new_owner_user_id_or_email:
          type: string
          minLength: 1
          title: New Owner User Id Or Email
      type: object
      required:
      - new_owner_user_id_or_email
      title: TransferTemplateOwnershipInput
      description: 'Input for ``POST /v1/templates/{template_identifier}/transfer-ownership``.


        Mirrors ``transfer_skill_ownership`` body shape: a UUID string or

        an email address resolves to a user. Team targets are rejected at the

        service layer with ``InvalidGranteeType``.'
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PublishTemplateVersionInput:
      properties:
        skill_id:
          type: string
          maxLength: 512
          minLength: 1
          title: Skill Id
          description: Skill UUID (string) or slug (same as the skill's ``name``).
        release_notes:
          anyOf:
          - type: string
            maxLength: 4096
          - type: 'null'
          title: Release Notes
      type: object
      required:
      - skill_id
      title: PublishTemplateVersionInput
      description: Input for ``publish_template_version``.
    ForkTemplateInput:
      properties:
        identifier:
          type: string
          maxLength: 128
          minLength: 1
          title: Identifier
        version:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Version
        name:
          anyOf:
          - type: string
            maxLength: 128
            minLength: 1
            pattern: ^[a-z0-9][a-z0-9-]*$
          - type: 'null'
          title: Name
      type: object
      required:
      - identifier
      title: ForkTemplateInput
      description: 'Input for ``fork_template``.


        ``identifier`` accepts a UUID string, ``@handle/slug``, or

        ``@handle/slug@vN``. ``version`` lets the caller pin to an older

        published version; default is the latest live version. ``name`` lets

        the caller override the fork''s slug; default is the template slug with

        a numeric suffix on caller-namespace collision.'