The apimatic.json Reference

How to configure your portal's branding and navigation, SDK languages and publishing, and Context Plugins.

apimatic.json is the APIMatic CLI's project file. It lives at src/apimatic.json and holds three things:

portal — the documentation portal built by apimatic portal generate and apimatic portal serve.
plugin — the Context Plugin's identity, recorded by apimatic plugin generate.
languages — the project's SDK languages, which apimatic sdk publish adds to.

Every section is optional. Add only the ones you use.

Example

src/apimatic.json

{
  "$schema": "https://cdn.jsdelivr.net/npm/@apimatic/cli@beta/apimatic.schema.json",
  "schemaVersion": 1,
  "portal": {
    "site": {
      "name": "Acme Payments",
      "url": "https://docs.acme.com",
      "description": "Accept payments and manage payouts with the Acme API."
    },
    "brand": {
      "colors": {
        "primary": { "light": "#1d4ed8", "dark": "#60a5fa" }
      },
      "colorMode": "both"
    },
    "navigation": {
      "links": [
        { "label": "Dashboard", "url": "https://dashboard.acme.com" },
        { "label": "Changelog", "url": "/changelog" }
      ]
    },
    "ai": {
      "pageActions": true
    },
    "pluginUrl": "https://plugins.acme.com/acme-payments"
  },
  "plugin": {
    "pluginId": "acme-payments",
    "pluginName": "Acme Payments",
    "pluginVersion": "0.1.0",
    "author": { "name": "Acme", "email": "devrel@acme.com" },
    "license": "MIT"
  },
  "languages": {
    "csharp": {
      "publishing": {
        "source": { "repositoryUrl": "https://github.com/acme/acme-csharp", "branch": "main" },
        "package": { "version": "1.2.0" },
        "packageConfiguration": { "packageId": "Acme.Payments" }
      }
    },
    "typescript": {
      "publishing": {
        "source": { "repositoryUrl": "https://github.com/acme/acme-typescript", "branch": "main" },
        "package": { "version": "1.2.0" },
        "packageConfiguration": { "name": "@acme/payments" }
      }
    },
    "python": {}
  }
}

Add the $schema line to get autocomplete and validation in VS Code and other JSON-aware editors. The CLI ignores it.

Top-level properties

Property	Type	Required	Description
`$schema`	string	No	Where editors find the JSON schema. Ignored by the CLI.
`schemaVersion`	`1`	No	Format of this file. Must be `1`; the CLI refuses a version it does not read.
`portal`	object	No	Documentation portal settings.
`plugin`	object	No	Context plugin identity.
`languages`	object	No	SDK languages and where they are published.

Unknown top-level properties are allowed and ignored.

portal

Configures the portal built by apimatic portal generate and apimatic portal serve. Unknown properties are not allowed anywhere inside portal.

Property	Type	Description
`site`	object	Name, address, and description of the portal.
`brand`	object	Logo, favicon, colors, and color mode.
`navigation`	object	Header links.
`ai`	object	AI features on portal pages.
`pluginUrl`	string	Where the Context Plugin is hosted. Must start with `https://` and contain no spaces. The Context Plugin page installs the plugin from here; the portal does not carry its own copy.

portal.site

Property	Type	Default	Description
`name`	string (non-blank)	Title of the only specification	The portal's name. Required when the `spec` directory holds more than one specification.
`url`	string	—	Address the portal is served from, for example, `https://docs.example.com` or `https://acme.github.io/docs`. It can include a path, and the portal is then built to be served under that path; canonical links, `og:url`, and the sitemap use it too. Each part of the path can contain only letters, digits, `.`, `_`, `~`, and `-`. Don't include a page name such as `index.html`, or `?`, `#`, or `\`. `http://` and `https://` are accepted; a single trailing `/` is allowed.
`description`	string	First paragraph of the only specification's description	Portal description. An empty string means no description.

portal.brand

Property	Type	Default	Description
`logo`	static path or `{ light, dark }`	—	One image for both color modes, or one per mode. When using the object form, both `light` and `dark` are required.
`favicon`	static path	The light logo	Browser tab icon.
`colors.primary`	color or `{ light, dark }`	—	Primary brand color for both modes, or one per mode. When using the object form, both `light` and `dark` are required.
`colorMode`	`"light"` \| `"dark"` \| `"both"`	`"both"`	Color modes the portal offers. Forcing `light` or `dark` hides the theme switch.

One logo and color for both modes

"brand": {
  "logo": "static/images/logo.svg",
  "colors": { "primary": "#1d4ed8" }
}

portal.navigation

Property	Type	Description
`links`	array of link	Links shown in the header and the mobile menu, in order.

portal.ai

Property	Type	Default	Description
`pageActions`	boolean	`true`	Whether each page shows the Copy Markdown button and the Open menu (View as Markdown, Scira AI, ChatGPT, Claude, Cursor). See Markdown for Every Page.

plugin

The Context Plugin's identity, recorded by apimatic plugin generate. Unknown properties are allowed.

Property	Type	Required	Description
`pluginId`	string	Yes	Lower-case alphanumeric words separated by single dashes, for example, `acme-payments`.
`pluginName`	string (non-blank)	Yes	Display name, for example, `Acme Payments`.
`pluginVersion`	string	Yes	`major.minor.patch`, for example, `0.1.0`.
`pluginKey`	string	No	Plugin key.
`author.name`	string	No	Author name.
`author.email`	string	No	Author email.
`license`	string	No	License identifier, for example, `MIT`.

pluginId, pluginName, and pluginVersion are all required to generate the plugin. If plugin is present without them, the file fails validation.

languages

The project's SDK languages. apimatic sdk publish adds to this section. Keys must be one of:

csharp · python · typescript

An entry without publishing marks a language that is wanted but not yet published, for example, "python": {}.

Unknown properties are not allowed anywhere inside languages: not on a language entry, nor in publishing, source, package, or packageConfiguration.

Language entry

Property	Type	Description
`publishing`	object	Where the SDK is published. Omit it for a language that isn't published yet.
`publishing.source`	object	The Git repository the SDK source was published to.
`publishing.source.repositoryUrl`	string	Repository URL.
`publishing.source.branch`	string	Branch.
`publishing.package`	object	The published release.
`publishing.package.version`	string	Released version, `major.minor.patch`, for example, `1.2.0`.
`publishing.packageConfiguration`	object	How the package is set up in its registry. Fields depend on the language; see below. Required when `package` is present.

publishing.package holds only the version. The package's name lives in packageConfiguration.

apimatic sdk publish writes packageConfiguration from your publishing profile, so you rarely edit it by hand. The portal's SDK card uses the package name in it for the install command.

packageConfiguration by language

Only the package name is required. Every other field is optional and, unless noted, accepts a string or null.

C# (NuGet)

Property	Type	Required	Description
`packageId`	string	Yes	NuGet package ID.
`authors`	string \| null	No	Package authors.
`description`	string \| null	No	Package description.
`title`	string \| null	No	Package title.
`packageTags`	string \| null	No	Tags.
`repositoryUrl`	string \| null	No	Source repository URL.
`repositoryType`	string \| null	No	Repository type, for example, `git`.
`packageProjectUrl`	string \| null	No	Project homepage.
`packageIcon`	string \| null	No	Package icon.
`packageReleaseNotes`	string \| null	No	Release notes.
`copyright`	string \| null	No	Copyright notice.

Python (PyPI)

Property	Type	Required	Description
`name`	string	Yes	PyPI project name.
`description`	string \| null	No	Package description.
`authors`	array of `{ name, email }`	No	Authors. Both fields are string or `null`.
`maintainers`	array of `{ name, email }`	No	Maintainers. Both fields are string or `null`.
`keywords`	array of string	No	Keywords.
`classifiers`	array of string	No	Trove classifiers.
`urls`	object of string	No	Project URLs keyed by label, for example, `{ "Documentation": "https://docs.acme.com" }`.

TypeScript (npm)

Property	Type	Required	Description
`name`	string	Yes	npm package name.
`description`	string \| null	No	Package description.
`author`	`{ name, email, url }`	No	Package author.
`contributors`	array of `{ name, email, url }`	No	Contributors.
`bugs`	`{ url, email }`	No	Where to report issues.
`keywords`	array of string	No	Keywords.
`homepage`	string \| null	No	Homepage URL.
`repository`	`{ type, url, directory }`	No	Source repository.

Fields inside author, contributors, bugs, and repository are string or null.

Examples

"languages": {
  "csharp": {
    "publishing": {
      "package": { "version": "1.0.0" },
      "packageConfiguration": { "packageId": "Acme.Payments" }
    }
  },
  "python": {
    "publishing": {
      "source": { "repositoryUrl": "https://github.com/acme/acme-python", "branch": "main" },
      "package": { "version": "1.0.0" },
      "packageConfiguration": {
        "name": "acme-payments",
        "description": "Python SDK for the Acme Payments API.",
        "authors": [{ "name": "Acme", "email": "devrel@acme.com" }]
      }
    }
  },
  "typescript": {}
}

Value formats

Static paths

Paths to files inside src/static, written relative to src, for example, static/images/logo.png. A leading ./ is allowed; . and .. segments are not.

✅ Valid	❌ Invalid
`static/images/logo.png`	`images/logo.png` (not under `static`)
`./static/logo.svg`	`static/../logo.png` (`..` segment)
`static\images\logo.png`	`static` (no file)

Colors

#rgb or #rrggbb hex, for example, #1d4ed8 or #fff. Case-insensitive.

Links

Property	Type	Required	Description
`label`	string (non-blank)	Yes	Text shown for the link.
`url`	string	Yes	A portal page starting with `/` (for example, `/changelog`), or an external address starting with `https://` or `http://`. Protocol-relative URLs such as `//example.com` are rejected.

Unknown properties are not allowed on links.

The apimatic.json Reference

ExampleCopy Anchor Link

Top-level propertiesCopy Anchor Link

portalCopy Anchor Link

portal.siteCopy Anchor Link

portal.brandCopy Anchor Link

portal.navigationCopy Anchor Link

portal.aiCopy Anchor Link

pluginCopy Anchor Link

languagesCopy Anchor Link

Language entryCopy Anchor Link

packageConfiguration by languageCopy Anchor Link

C# (NuGet)Copy Anchor Link

Python (PyPI)Copy Anchor Link

TypeScript (npm)Copy Anchor Link

Value formatsCopy Anchor Link

Static pathsCopy Anchor Link

ColorsCopy Anchor Link

LinksCopy Anchor Link

On this page