{"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"]}}}}}}