Getting Started

Install

With uv:

uv add APICORE_Python

With pip:

pip install APICORE_Python

The installation contains only the Python library. CLI and GUI tools are available from a repository checkout under tools/.

Load A File

from apicore import load

document = load("example.api.yaml")
print(document.apicore_version)
print(document.friendly_name)

The format is inferred from .json, .yaml, .yml, or .toml. Use format= to override inference.

Load In-Memory Data

from apicore import loads

document = loads(
    '{"friendly_name":"Demo","link":"https://api.example.com/x",'
    '"func":"GET","parameters":[],"response":{'
    '"media":{"type":"text","content_type":"BINARY","path":"data.text"}}}'
)

assert document.apicore_version == "2.1"

loads() defaults to JSON. Pass format="yaml" or format="toml" for other formats.

Parse A Mapping

from apicore import parse

document = parse(
    {
        "friendly_name": "Demo",
        "link": "https://api.example.com/x",
        "func": "GET",
        "parameters": [],
        "response": {
            "image": {"content_type": "URL", "path": "data.url"}
        },
    }
)

assert document.apicore_version == "2.0"

parse() reads but does not modify the supplied mapping. This document has no version declaration or v2.1-only fields, so it retains APICORE 2.0 semantics. Undeclared documents containing features such as response.media, localized UI values, polling, or enum options are inferred as APICORE 2.1.

Handle Errors

from apicore import APICoreError, ParseError, ValidationError, load

try:
    document = load("example.api.yaml")
except ParseError as exc:
    print(f"Syntax error: {exc}")
except ValidationError as exc:
    print(f"Schema error: {exc}")
except OSError as exc:
    print(f"File error: {exc}")
except APICoreError as exc:
    print(f"APICORE error: {exc}")

Resolve Localized Text

from apicore import resolve_i18n

name = {"zh-CN": "绘图", "en-US": "Image Generation"}
assert resolve_i18n(name, "zh-CN") == "绘图"
assert resolve_i18n(name, "ja-JP", fallback_locale="en-US") == "Image Generation"

Read Response Media

Use preferred_media to support both v2.1 media and legacy image configurations:

media = document.response.preferred_media
if media is not None:
    print(media.type, media.content_type, media.path)