{
  "openapi": "3.1.0",
  "info": {
    "title": "Arcs for iPhone Product Information API",
    "version": "1.0.0",
    "license": {
      "name": "Arcs API Terms",
      "url": "https://arcsforiphone.com/terms"
    },
    "summary": "Canonical, read-only product information about Arcs for iPhone.",
    "description": "The Arcs Product Information API exposes public product facts, capabilities, canonical resources and service health. It cannot access or operate a user's private on-device content. Stable major versions appear in the URL. Additive fields may be introduced within a version; breaking changes require a new major path. A version scheduled for removal will be announced at least 180 days in advance through the developer guide, the Deprecation response header, a Sunset header and linked migration guidance."
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [{"url": "https://arcsforiphone.com", "description": "Production"}],
  "security": [],
  "tags": [
    {"name": "Discovery", "description": "Discover API operations and canonical resources."},
    {"name": "Product", "description": "Retrieve canonical facts about Arcs and its workflow."},
    {"name": "Operations", "description": "Check availability of the public information API."}
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "getApiIndex",
        "summary": "Get the API index",
        "description": "Returns the current API version, purpose, endpoint list and documentation links.",
        "tags": ["Discovery"],
        "responses": {
          "200": {"description": "API index", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiIndex"}}}},
          "406": {"$ref": "#/components/responses/NotAcceptable"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "500": {"$ref": "#/components/responses/InternalError"}
        }
      }
    },
    "/api/v1/product": {
      "get": {
        "operationId": "getProduct",
        "summary": "Get canonical Arcs product facts",
        "description": "Returns the product identity, promise, supported platforms, workflow and privacy architecture.",
        "tags": ["Product"],
        "responses": {
          "200": {"description": "Canonical product record", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProductResponse"}}}},
          "406": {"$ref": "#/components/responses/NotAcceptable"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "500": {"$ref": "#/components/responses/InternalError"}
        }
      }
    },
    "/api/v1/capabilities": {
      "get": {
        "operationId": "listCapabilities",
        "summary": "List the Arcs workflow capabilities",
        "description": "Returns typed descriptions of Record, Read, Threads, Next and Build.",
        "tags": ["Product"],
        "responses": {
          "200": {"description": "Capability list", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CapabilitiesResponse"}}}},
          "406": {"$ref": "#/components/responses/NotAcceptable"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "500": {"$ref": "#/components/responses/InternalError"}
        }
      }
    },
    "/api/v1/resources": {
      "get": {
        "operationId": "listResources",
        "summary": "List canonical Arcs resources",
        "description": "Returns stable links to product, help, privacy, press, developer and agent resources.",
        "tags": ["Discovery"],
        "responses": {
          "200": {"description": "Canonical resource list", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ResourcesResponse"}}}},
          "406": {"$ref": "#/components/responses/NotAcceptable"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "500": {"$ref": "#/components/responses/InternalError"}
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "getApiHealth",
        "summary": "Check API health",
        "description": "Returns the current availability and version of the public product-information API.",
        "tags": ["Operations"],
        "responses": {
          "200": {"description": "Service is available", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/HealthResponse"}}}},
          "406": {"$ref": "#/components/responses/NotAcceptable"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "500": {"$ref": "#/components/responses/InternalError"}
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Meta": {
        "type": "object",
        "required": ["apiVersion"],
        "properties": {"apiVersion": {"type": "string", "const": "1.0.0"}, "count": {"type": "integer", "minimum": 0}},
        "additionalProperties": false
      },
      "Architecture": {
        "type": "object",
        "required": ["processing", "offline", "dataServers", "optionalSync"],
        "properties": {
          "processing": {"type": "string", "examples": ["On device"]},
          "offline": {"type": "boolean"},
          "dataServers": {"type": "boolean"},
          "optionalSync": {"type": "string"}
        },
        "additionalProperties": false
      },
      "Product": {
        "type": "object",
        "required": ["name", "fullName", "description", "promise", "url", "platforms", "availability", "workflow", "architecture"],
        "properties": {
          "name": {"type": "string", "const": "Arcs"},
          "fullName": {"type": "string", "const": "Arcs for iPhone"},
          "description": {"type": "string"},
          "promise": {"type": "string"},
          "url": {"type": "string", "format": "uri"},
          "platforms": {"type": "array", "items": {"type": "string"}, "minItems": 1},
          "availability": {"type": "string"},
          "workflow": {"type": "array", "items": {"type": "string"}, "minItems": 5, "maxItems": 5},
          "architecture": {"$ref": "#/components/schemas/Architecture"}
        },
        "additionalProperties": false
      },
      "Capability": {
        "type": "object",
        "required": ["id", "name", "description"],
        "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "description": {"type": "string"}},
        "additionalProperties": false
      },
      "Resource": {
        "type": "object",
        "required": ["rel", "title", "href"],
        "properties": {"rel": {"type": "string"}, "title": {"type": "string"}, "href": {"type": "string", "format": "uri"}},
        "additionalProperties": false
      },
      "ProductResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {"data": {"$ref": "#/components/schemas/Product"}, "meta": {"$ref": "#/components/schemas/Meta"}},
        "additionalProperties": false
      },
      "CapabilitiesResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Capability"}}, "meta": {"$ref": "#/components/schemas/Meta"}},
        "additionalProperties": false
      },
      "ResourcesResponse": {
        "type": "object",
        "required": ["data", "meta"],
        "properties": {"data": {"type": "array", "items": {"$ref": "#/components/schemas/Resource"}}, "meta": {"$ref": "#/components/schemas/Meta"}},
        "additionalProperties": false
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status", "service", "version"],
        "properties": {"status": {"type": "string", "const": "ok"}, "service": {"type": "string"}, "version": {"type": "string"}},
        "additionalProperties": false
      },
      "ApiIndex": {
        "type": "object",
        "required": ["api", "version", "description", "endpoints", "documentation", "openapi"],
        "properties": {
          "api": {"type": "string"}, "version": {"type": "string"}, "description": {"type": "string"},
          "endpoints": {"type": "array", "items": {"type": "string"}},
          "documentation": {"type": "string", "format": "uri"}, "openapi": {"type": "string", "format": "uri"}
        },
        "additionalProperties": false
      },
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details with Arcs-specific code and resolution extensions.",
        "required": ["type", "title", "status", "detail", "instance", "code", "resolution"],
        "properties": {
          "type": {"type": "string", "format": "uri-reference"},
          "title": {"type": "string"},
          "status": {"type": "integer", "minimum": 400, "maximum": 599},
          "detail": {"type": "string"},
          "instance": {"type": "string", "format": "uri-reference"},
          "code": {"type": "string", "pattern": "^[A-Z][A-Z0-9_]+$"},
          "resolution": {"type": "string"}
        },
        "additionalProperties": true
      }
    },
    "responses": {
      "NotAcceptable": {"description": "Requested representation is not available", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}},
      "RateLimited": {"description": "Request quota exceeded", "headers": {"Retry-After": {"schema": {"type": "integer"}, "description": "Seconds until the client should retry."}}, "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}},
      "InternalError": {"description": "Unexpected server error", "content": {"application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}}}
    }
  },
  "externalDocs": {"description": "Arcs for iPhone developer resources", "url": "https://arcsforiphone.com/developers"},
  "x-api-lifecycle": {
    "stability": "stable",
    "versioning": "Major version in URL path",
    "breakingChanges": "New major path",
    "deprecationNoticeDays": 180,
    "deprecationHeaders": ["Deprecation", "Sunset", "Link"]
  }
}