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."
  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
        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
            - cliInstructions
            - mcpServer
          properties:
            endpoints:
              type: object
            cliInstructions:
              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
        products:
          type: array
          items:
            type: object
        documentation:
          type: object
        endpoints:
          type: object
    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
        provider:
          type: object
        serviceCategory:
          type: string
        pricing:
          type: object
        endpoints:
          type: object
        auth:
          type: object
        checkout:
          type:
            - object
            - "null"
        payment:
          type:
            - object
            - "null"