generated: '2026-08-09' method: searched source: >- https://docs.autoderm.ai/en/getting-started/getting-started, https://docs.autoderm.ai/en/disease-detection-api/disease-detection-api, https://docs.autoderm.ai/en/support/api-versioning, and derived from openapi/autoderm-ai-dermatology-api-openapi.yml plus live response headers observed 2026-08-09. description: >- Cross-cutting request/response semantics for the Autoderm API — the runtime behavior that applies to every operation rather than to any single endpoint. Autoderm is a stateless single-shot inference API: every call uploads one image and returns one ranked prediction set. That shape means several conventions that most REST APIs need simply do not exist here (no collections to paginate, no resources to create twice), and this artifact records those absences explicitly rather than leaving them ambiguous. base_url: https://api.autoderm.ai api_style: >- REST over HTTPS. Requests are multipart/form-data file uploads on the inference endpoints; all responses are JSON. Generated by FastAPI (OpenAPI 3.1.0). authentication: scheme: HTTP Bearer token header: 'Authorization: Bearer YOUR_API_TOKEN' key_types: - organization API token issued from https://app.autoderm.ai server_side_only: true docs: https://docs.autoderm.ai/en/getting-started/getting-started detail: authentication/autoderm-ai-dermatology-api-authentication.yml idempotency: supported: false mechanism: null evidence: - No Idempotency-Key (or equivalent) parameter or header appears anywhere in the OpenAPI. - No idempotency section exists in the published documentation. analysis: >- All five write-shaped operations are POSTs, but each is a pure inference call: it creates no addressable server-side resource and returns a computed result. Re-sending the same image produces an equivalent prediction rather than a duplicate object, so the usual duplicate-charge hazard is limited to billing (each call is a metered "detection" on the Basic plan at $1.00 per call after the first 100). A retry that a client cannot distinguish from a first attempt is therefore a BILLING risk, not a data-integrity risk. recommendation_to_provider: >- An Idempotency-Key request header scoped to the metered inference endpoints would let clients retry a timed-out upload without being billed twice. This is the single highest-value agent-readiness gap on this API. pagination: supported: false reason: >- No operation returns a paged collection. The one list-shaped response, GET /v1/infer-diseases/v1/diseases, returns the complete static disease catalog in a single document and the docs instruct clients to fetch it once and cache it: "Clients should not call the catalog endpoint repeatedly at runtime." field_expansion: supported: false note: >- The closest equivalent is the include_skin_tone query parameter on POST /v1/infer-diseases/v1, which opts an extra model result (Fitzpatrick skin type) into the response envelope. request_options: description: Query parameters that alter inference behavior on the primary endpoint. operation: infer_diseases_v1_v1_infer_diseases_v1_post parameters: - name: include_skin_tone in: query type: boolean default: false description: Whether to include Fitzpatrick skin type prediction in the response. - name: require_anonymous in: query type: boolean default: false description: >- Whether to require the image to be anonymous. Images where the subject can be identified will be rejected. caveat: >- Docs are explicit that this "is intended as a supporting safeguard only. It does not guarantee full anonymisation of submitted images" and does not transfer data-protection responsibility to Autoderm. metadata: supported: false note: >- No client-supplied metadata field. Inference metadata (two-eyes, skin_detection, age, skin_tone) is computed server-side and stored by Autoderm; per the spec description, "age is never returned to the user". request_tracing: supported: true response_header: x-request-id format: UUID v4 observed_example_header: x-request-id additional_headers: - x-cloud-trace-context observed: '2026-08-09 — present on both 200 and 401 responses from api.autoderm.ai' documented: false note: >- The header is emitted by the platform but is not documented. The support page nonetheless asks customers to supply "Request identifiers or timestamps, if available" when opening a ticket, which is what this header is for. support_use: https://docs.autoderm.ai/en/support/support-contact versioning: scheme: semver + versioned URI path current: 2.3.6 path_form: /v1//v1 (platform version segment + model version segment) policy: https://docs.autoderm.ai/en/support/api-versioning detail: lifecycle/autoderm-ai-dermatology-api-lifecycle.yml discovery: - GET /version - GET /v1/system/version note: >- Both path segments are literal "v1" today; the second is the model generation, which is why the disease catalog is described as static "for a given model version". error_envelope: documented_shape: '422': schema: HTTPValidationError body: '{"detail": [{"loc": [...], "msg": "...", "type": "...", "input": ..., "ctx": {...}}]}' note: FastAPI's standard validation-error envelope. observed_shape: '401': body: '{"detail": "Missing Authorization header"}' note: >- Same "detail" key but a plain string rather than an array of ValidationError objects. Clients must handle both shapes. rfc9457: false content_type: application/json detail: errors/autoderm-ai-dermatology-api-problem-types.yml rate_limit_signaling: headers_documented: false headers_observed: none on 200/401 responses probed 2026-08-09 model: >- Quota-based rather than per-second throttling. Entitlement is a monthly detection count set by the plan; overage on Basic is billed at $1.00 per detection rather than rejected. detail: rate-limits/autoderm-ai-dermatology-api-rate-limits.yml payload_constraints: request: content_type: multipart/form-data field: image min_resolution: 224x224 max_file_size_docs: 5 MB max_file_size_spec: 10.00 MB discrepancy: >- OBSERVED CONFLICT — the getting-started and eIFU pages both state a 5 MB maximum, while every requestBody schema description in the live OpenAPI (Body_infer_diseases_v1_v1_infer_diseases_v1_post and siblings) states "Maximum size: 10.00 MB". Recorded as found; not reconciled. Clients should treat 5 MB as the safe ceiling. formats_docs: JPG, PNG, BMP, GIF, TIFF, WebP, DICOM (and related formats) response: content_type: application/json predictions: ranked, top 5, descending confidence confidence_range: 0 to 1 identifiers: ICD-10 caching: guidance: >- Fetch GET /v1/infer-diseases/v1/diseases once and cache it locally; it is guaranteed static for a given model version and is intended as a presentation/translation layer, not a runtime call. source: https://docs.autoderm.ai/en/disease-detection-api/migrating-from-legacy-api presentation_obligations: note: >- Unusual for a REST API and load-bearing for any integrator: Autoderm is a regulated medical device, so its documentation imposes MANDATORY UI requirements on the API consumer. These are conventions of the contract as much as any header is. mandatory_warning: 'Results are for information only and are not a medical diagnosis.' warning_rules: - The warning shall be clearly visible without scrolling. - It shall not be obscured by other UI elements. - It shall be displayed whenever results are shown to an end user. confidence_display: raw_percentages: not recommended for laypersons recommended_bands: high_possibility: 33% or higher possible: between 10% and 33% unlikely: less than 10% required_note_if_shown: >- "Confidence scores sum to 100% across the five displayed outputs. These values are normalised from probabilities calculated across all internal subclasses." docs: https://docs.autoderm.ai/en/medical-device/interface-creation cross_links: authentication: authentication/autoderm-ai-dermatology-api-authentication.yml errors: errors/autoderm-ai-dermatology-api-problem-types.yml lifecycle: lifecycle/autoderm-ai-dermatology-api-lifecycle.yml rate_limits: rate-limits/autoderm-ai-dermatology-api-rate-limits.yml conformance: conformance/autoderm-ai-dermatology-api-conformance.yml data_model: data-model/autoderm-ai-dermatology-api-data-model.yml