openapi: 3.1.0
info:
  title: Ivy Public Agent API
  version: 1.0.0
  description: "Public, machine-readable OpenAPI 3.1 specification for Ivy Tendril: The Agentic Software Factory for 10x Builders. Orchestrates any CLI coding agent with parallel worktrees, Cloudflare Quick Tunnels, Whisper voice input, inline plan annotations, and automated code review verification gates. See /llms.txt and /llms-full.txt for agent guidance.\n\nVersioning: operations are versioned in the path (/api/v1/). Breaking changes ship under a new path version rather than mutating an existing one.\n\nDeprecation: a retiring operation is first marked `deprecated: true` in this document and begins serving a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) giving the removal date, at least 180 days ahead of removal. Clients should treat the presence of either header as a signal to migrate, and the `Link` relation `rel=\"deprecation\"` as pointing at the migration notes.\n\nRate limits: every response carries IETF `RateLimit-*` headers describing the request budget. Exhausting it yields 429 with `Retry-After` and an RFC 9457 problem document."
  contact:
    name: Ivy Interactive AB
    url: "https://ivy.app"
    email: "support@ivy.app"
  license:
    name: Functional Source License (FSL-1.1-ALv2)
    url: "https://github.com/Ivy-Interactive/Ivy-Tendril/blob/main/LICENSE"
servers:
  -     url: "https://ivy.app"
        description: Production API server
tags:
  -     name: Agent
        description: "Endpoints for AI agents, CLI tooling, and automated workflows"
  -     name: Discovery
        description: "Machine-readable manifests, specifications, and provider discovery"
  -     name: Auth
        description: Authentication and authorization server discovery metadata
  -     name: Media
        description: Dynamic image and media generation endpoints
paths:
  /api/v1/agent/downloads:
    get:
      tags:
        - Agent
      operationId: getTendrilDownloads
      summary: Get the latest Ivy Tendril download links
      description: "Returns the latest published Ivy Tendril release version and platform-specific installer download URLs, sourced live from the GitHub Releases API."
      responses:
        "200":
          description: Latest Tendril release and available platform installers.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TendrilDownloadsResponse"
        "503":
          description: Upstream GitHub release data is temporarily unavailable.
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /api/v1/agent/capabilities:
    get:
      tags:
        - Agent
      operationId: getAgentCapabilities
      summary: Get supported AI agents and models for Ivy Tendril
      description: "Returns the set of CLI-based coding agents and LLM models that Ivy Tendril currently supports, along with links to fuller documentation."
      responses:
        "200":
          description: "Supported agents, models, and related documentation links."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentCapabilitiesResponse"
  /api/v1/agent/instructions:
    get:
      tags:
        - Agent
      operationId: getAgentInstructions
      summary: Get agent instructions and when-to-use guidance
      description: "Returns structured guidance for AI agents on when to reach for Ivy Tendril, best-fit criteria, workflow execution rules, and self-serve onboarding instructions."
      responses:
        "200":
          description: Structured instructions and guidance for AI agents.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentInstructionsResponse"
  /api/v1/agent/context:
    get:
      tags:
        - Agent
      operationId: getAgentContext
      summary: Get full product and developer context for LLM ingestion
      description: "Returns structured product taxonomy, documentation URLs, pricing tier summaries, and repository links formatted for LLM system prompts and context grounding."
      responses:
        "200":
          description: Structured context document for LLMs and agents.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentContextResponse"
  /api/og:
    get:
      tags:
        - Media
      operationId: generateOgImage
      summary: Generate a social share (OG) image
      description: "Renders a dynamic Open Graph / social share image for a given title and seed, used for link previews across the marketing site."
      parameters:
        -           name: title
                    in: query
                    required: false
                    description: "Headline text rendered on the image. Defaults to \"Ivy\"."
                    schema:
                      type: string
                      default: Ivy
        -           name: seed
                    in: query
                    required: false
                    description: "Seed used to vary the generated background pattern. Defaults to \"default\"."
                    schema:
                      type: string
                      default: default
      responses:
        "200":
          description: Generated PNG image.
          content:
            image/png:
              schema:
                type: string
                format: binary
  /openapi.json:
    get:
      tags:
        - Discovery
      operationId: getOpenApiJsonSpec
      summary: Get OpenAPI 3.1 specification in JSON format
      description: Returns the full machine-readable OpenAPI 3.1 specification describing Ivy public APIs in JSON format.
      responses:
        "200":
          description: OpenAPI 3.1 specification document in JSON.
          content:
            application/json:
              schema:
                type: object
  /openapi.yaml:
    get:
      tags:
        - Discovery
      operationId: getOpenApiYamlSpec
      summary: Get OpenAPI 3.1 specification in YAML format
      description: Returns the full machine-readable OpenAPI 3.1 specification describing Ivy public APIs in YAML format.
      responses:
        "200":
          description: OpenAPI 3.1 specification document in YAML.
          content:
            text/yaml:
              schema:
                type: string
  /.well-known/oauth-authorization-server:
    get:
      tags:
        - Auth
      operationId: getOAuthAuthorizationServerMetadata
      summary: Get OAuth 2.0 Authorization Server Metadata (RFC 8414)
      description: "Returns OAuth 2.0 authorization server metadata including issuer, token/authorization endpoints, supported scopes, and grant types."
      responses:
        "200":
          description: RFC 8414 authorization server metadata.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OAuthAuthorizationServerMetadata"
  /.well-known/openid-configuration:
    get:
      tags:
        - Auth
      operationId: getOpenIdConfiguration
      summary: Get OpenID Connect Discovery configuration
      description: Returns OpenID Connect discovery metadata for identity and authentication integration.
      responses:
        "200":
          description: OpenID Connect configuration document.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpenIdConfiguration"
  /.well-known/ucp/manifest.json:
    get:
      tags:
        - Discovery
      operationId: getUcpManifest
      summary: Get Universal Commerce Protocol (UCP) provider manifest
      description: "Returns the Universal Commerce Protocol manifest describing Ivy provider identity, public endpoints, and pricing tiers."
      responses:
        "200":
          description: UCP manifest JSON document.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UcpManifestResponse"
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 authentication for automated agent workflows and developer integrations.
      flows:
        authorizationCode:
          authorizationUrl: "https://ivy.app/auth/oauth/authorize"
          tokenUrl: "https://ivy.app/auth/oauth/token"
          scopes:
            "agent:read": "Read agent capabilities, release downloads, and instructions"
            "agent:write": "Trigger agent workflow executions, task planning, and draft PR generation"
            "repo:read": "Read repository metadata, issues, and git worktrees"
            "repo:write": "Create branches, push commits, and open pull requests"
            "billing:read": View billing plan and credit balances
        clientCredentials:
          tokenUrl: "https://ivy.app/auth/oauth/token"
          scopes:
            "agent:read": "Read agent capabilities, release downloads, and instructions"
            "agent:write": "Trigger agent workflow executions, task planning, and draft PR generation"
            "repo:read": "Read repository metadata, issues, and git worktrees"
            "repo:write": "Create branches, push commits, and open pull requests"
            "billing:read": View billing plan and credit balances
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "JWT Bearer token authentication supporting scoped roles (agent:read, agent:write)."
  schemas:
    ProblemDetails:
      type: object
      description: RFC 7807 problem details error response with resolution hints for AI agents.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
          description: A URI reference identifying the problem type.
          example: "https://ivy.app/docs/errors/not-found"
        title:
          type: string
          description: "A short, human-readable summary of the problem type."
          example: Not Found
        status:
          type: integer
          description: The HTTP status code generated by the origin server.
          example: 404
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence.
          example: This API endpoint does not exist. See /openapi.json for available endpoints.
        instance:
          type: string
          format: uri
          description: A URI reference that identifies the specific occurrence of the problem.
        code:
          type: string
          description: A machine-readable error code string for programmatic agent branching.
          example: API_ENDPOINT_NOT_FOUND
        resolution:
          type: string
          description: Actionable guidance on how an agent or client can resolve the issue.
          example: Check the URL against the published OpenAPI specification at /openapi.json.
    DownloadPlatform:
      type: object
      required:
        - target
        - os
        - arch
        - format
        - url
      properties:
        target:
          type: string
          enum:
            - osx-arm64
            - osx-x64
            - win-x64
            - win-arm64
            - linux-x64
            - linux-arm64
          description: Platform target identifier.
        os:
          type: string
          enum:
            - macos
            - windows
            - linux
          description: Operating system.
        arch:
          type: string
          enum:
            - arm64
            - x64
          description: Processor architecture.
        format:
          type: string
          enum:
            - pkg
            - exe
            - AppImage
          description: Installer package format.
        url:
          type: string
          format: uri
          description: Direct download URL for the installer asset.
    TendrilDownloadsResponse:
      type: object
      required:
        - product
        - version
        - releaseUrl
        - platforms
      properties:
        product:
          type: string
          example: Ivy Tendril
          description: Product name.
        version:
          type: string
          example: 1.4.2
          description: Latest semantic release version.
        releaseUrl:
          type: string
          format: uri
          example: "https://github.com/Ivy-Interactive/Ivy-Tendril/releases/tag/v1.4.2"
          description: GitHub Release page URL.
        platforms:
          type: array
          items:
            $ref: "#/components/schemas/DownloadPlatform"
          description: List of platform-specific installers.
    AgentCapabilityEntry:
      type: object
      required:
        - name
        - vendor
      properties:
        name:
          type: string
          example: Claude Code
        vendor:
          type:
            - string
            - "null"
          example: Anthropic
    ModelCapabilityEntry:
      type: object
      required:
        - name
        - via
      properties:
        name:
          type: string
          example: Claude Sonnet
        via:
          type: string
          example: Claude Code
    AgentCapabilitiesResponse:
      type: object
      required:
        - product
        - agents
        - models
        - links
      properties:
        product:
          type: string
          example: Ivy Tendril
        agents:
          type: array
          items:
            $ref: "#/components/schemas/AgentCapabilityEntry"
        models:
          type: array
          items:
            $ref: "#/components/schemas/ModelCapabilityEntry"
        notes:
          type: string
        links:
          type: object
          required:
            - docs
            - github
            - llmsTxt
            - llmsFullTxt
          properties:
            docs:
              type: string
              format: uri
            github:
              type: string
              format: uri
            llmsTxt:
              type: string
              format: uri
            llmsFullTxt:
              type: string
              format: uri
    AgentInstructionsResponse:
      type: object
      required:
        - product
        - whenToUse
        - whenNotToUse
        - howToCall
        - onboarding
      properties:
        product:
          type: string
          example: Ivy Tendril
        tagline:
          type: string
        vision:
          type: string
        version:
          type: string
          example: 1.0.0
        keyFeatures:
          type: array
          description: "Headline capabilities, each with a one-paragraph explanation."
          items:
            type: object
            required:
              - name
              - description
            properties:
              name:
                type: string
              description:
                type: string
        supportedAgents:
          type: array
          items:
            type: string
          description: CLI coding agents Tendril can orchestrate.
        links:
          type: object
          description: "Canonical URLs for the product, its docs, and its communities."
          properties:
            website:
              type: string
              format: uri
            tendrilSite:
              type: string
              format: uri
            docs:
              type: string
              format: uri
            github:
              type: string
              format: uri
            discord:
              type: string
              format: uri
            llmsTxt:
              type: string
              format: uri
            openapi:
              type: string
              format: uri
        whenToUse:
          type: array
          items:
            type: string
          description: Best-fit scenarios for recommending or triggering Ivy Tendril.
        whenNotToUse:
          type: array
          items:
            type: string
          description: Scenarios where Tendril is not applicable.
        howToCall:
          type: object
          required:
            - endpoints
            - cliInstall
            - mcpServer
          properties:
            endpoints:
              type: object
              description: The subset of public endpoints an agent needs to act on this product.
              required:
                - downloads
                - capabilities
                - context
                - openapi
              properties:
                downloads:
                  type: string
                  format: uri
                capabilities:
                  type: string
                  format: uri
                context:
                  type: string
                  format: uri
                openapi:
                  type: string
                  format: uri
            cliInstall:
              type: object
              description: "Copy-pasteable install and launch commands, per platform."
              required:
                - macAndLinux
                - windows
                - runDesktop
                - runHeadless
              properties:
                macAndLinux:
                  type: string
                windows:
                  type: string
                runDesktop:
                  type: string
                runHeadless:
                  type: string
            mcpServer:
              type: string
        onboarding:
          type: object
          required:
            - freeTier
            - selfServe
            - sandbox
          properties:
            freeTier:
              type: string
            selfServe:
              type: string
            sandbox:
              type: string
    AgentContextResponse:
      type: object
      required:
        - company
        - products
        - documentation
        - endpoints
      properties:
        company:
          type: object
          required:
            - name
            - legalName
            - founded
            - location
            - website
          properties:
            name:
              type: string
              example: Ivy Interactive AB
            brand:
              type: string
              example: Ivy
            legalName:
              type: string
            founded:
              type: integer
              example: 2025
            location:
              type: string
              example: "Stockholm, Sweden"
            website:
              type: string
              format: uri
            mission:
              type: string
            founders:
              type: array
              items:
                type: object
                required:
                  - name
                  - role
                properties:
                  name:
                    type: string
                  role:
                    type: string
                  email:
                    type: string
                    format: email
            social:
              type: object
              properties:
                github:
                  type: string
                  format: uri
                discord:
                  type: string
                  format: uri
                linkedin:
                  type: string
                  format: uri
                twitter:
                  type: string
                  format: uri
        products:
          type: array
          items:
            $ref: "#/components/schemas/AgentContextProduct"
        documentation:
          type: object
          description: "Every documentation surface, human- and machine-readable."
          properties:
            tendrilDocs:
              type: string
              format: uri
            docsUrl:
              type: string
              format: uri
            llmsTxt:
              type: string
              format: uri
            llmsFullTxt:
              type: string
              format: uri
            openapiJson:
              type: string
              format: uri
            openapiYaml:
              type: string
              format: uri
        endpoints:
          type: object
          description: "Every public machine-readable endpoint, including discovery documents."
          required:
            - downloads
            - capabilities
            - instructions
            - context
          properties:
            downloads:
              type: string
              format: uri
            capabilities:
              type: string
              format: uri
            instructions:
              type: string
              format: uri
            context:
              type: string
              format: uri
            oauthMetadata:
              type: string
              format: uri
            openidConfiguration:
              type: string
              format: uri
            ucpManifest:
              type: string
              format: uri
    AgentContextProduct:
      type: object
      description: One Ivy product. Tendril carries the full block; the framework entry omits the fields that only apply to a distributed desktop application.
      required:
        - id
        - name
        - category
        - description
      properties:
        id:
          type: string
          example: ivy-tendril
        name:
          type: string
        tagline:
          type: string
        category:
          type: string
        architecture:
          type: string
        license:
          type: string
          example: Functional Source License (FSL-1.1-ALv2)
        repository:
          type: string
          format: uri
        description:
          type: string
        features:
          type: array
          items:
            type: string
        supportedAgents:
          type: array
          items:
            type: string
        installCommands:
          type: object
          properties:
            macAndLinux:
              type: string
            windows:
              type: string
            runDesktop:
              type: string
            runHeadless:
              type: string
        pricingTiers:
          type: array
          items:
            type: object
            required:
              - id
              - name
              - priceMonthly
            properties:
              id:
                type: string
              name:
                type: string
              priceMonthly:
                type: string
                description: "Formatted monthly price, or the literal \"Custom\"."
                example: $20
              summary:
                type: string
    OAuthAuthorizationServerMetadata:
      type: object
      required:
        - issuer
        - authorization_endpoint
        - token_endpoint
        - jwks_uri
        - scopes_supported
        - response_types_supported
        - grant_types_supported
      properties:
        issuer:
          type: string
          format: uri
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        jwks_uri:
          type: string
          format: uri
        scopes_supported:
          type: array
          items:
            type: string
        response_types_supported:
          type: array
          items:
            type: string
        grant_types_supported:
          type: array
          items:
            type: string
        token_endpoint_auth_methods_supported:
          type: array
          items:
            type: string
        service_documentation:
          type: string
          format: uri
        code_challenge_methods_supported:
          type: array
          items:
            type: string
    OpenIdConfiguration:
      type: object
      required:
        - issuer
        - authorization_endpoint
        - token_endpoint
        - userinfo_endpoint
        - jwks_uri
        - scopes_supported
        - response_types_supported
        - subject_types_supported
        - id_token_signing_alg_values_supported
      properties:
        issuer:
          type: string
          format: uri
        authorization_endpoint:
          type: string
          format: uri
        token_endpoint:
          type: string
          format: uri
        userinfo_endpoint:
          type: string
          format: uri
        jwks_uri:
          type: string
          format: uri
        scopes_supported:
          type: array
          items:
            type: string
        response_types_supported:
          type: array
          items:
            type: string
        subject_types_supported:
          type: array
          items:
            type: string
        id_token_signing_alg_values_supported:
          type: array
          items:
            type: string
    UcpManifestResponse:
      type: object
      required:
        - ucpVersion
        - provider
        - serviceCategory
        - pricing
        - endpoints
        - auth
      properties:
        ucpVersion:
          type: string
          example: latest
        provider:
          type: object
          required:
            - name
            - url
          properties:
            name:
              type: string
              example: Ivy Interactive AB
            url:
              type: string
              format: uri
            contact:
              type: string
              format: email
        serviceCategory:
          type: string
          example: developer-tools
        pricing:
          type: object
          required:
            - pricingUrl
            - currency
            - tiers
          properties:
            pricingUrl:
              type: string
              format: uri
            currency:
              type: string
              example: USD
            tiers:
              type: array
              items:
                type: object
                required:
                  - id
                  - name
                  - price
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  price:
                    type:
                      - number
                      - "null"
                  billingPeriod:
                    type: string
                    example: month
                  priceLabel:
                    type: string
                  description:
                    type: string
        endpoints:
          type: object
          required:
            - downloads
            - capabilities
            - openapi
          properties:
            downloads:
              type: string
              format: uri
            capabilities:
              type: string
              format: uri
            openapi:
              type: string
              format: uri
        auth:
          type: object
          required:
            - model
          properties:
            model:
              type: string
              enum:
                - none
              description: All listed endpoints are public and read-only.
            description:
              type: string
        checkout:
          type:
            - object
            - "null"
        payment:
          type:
            - object
            - "null"