Specify API Metadata

Add an APIMatic Metadata file next to your API definition to filter endpoints, properties, and parameters, or override servers, authentication, and other details.

The APIMatic Metadata file is a JSON file that sits next to your API definition and tells APIMatic how to process it.

Add the metadata file

Create a file whose name starts with APIMATIC-META, for example APIMATIC-META.json.
Put it in the same folder as your API definition, not in a subfolder:
```
src/
  spec/
    openapi.yaml
    APIMATIC-META.json
```
Add the settings you need. The file must be valid JSON.

APIMatic checks the file against the Metadata File Validation ruleset when it validates your definition.

src/spec/APIMATIC-META.json

{
  "ImportSettings": {
    "PreferJsonSchemaNameOverTitle": true,
    "PreferSwaggerOperationSummaryOverId": false
  },
  "ExportSettings": {
    "ExportExtensions": false,
    "EncodeUrlParamsInPostman": true
  },
  "MergeConfiguration": {
    "MergeApis": false
  }
}

Top-level sections

Section	What it controls	See
`ImportSettings`	How the definition is read	Import and Export Settings
`ExportSettings`	How the definition is written when you transform it	Import and Export Settings
`ValidationConfiguration`	Which linting rulesets and rules run, and at what severity	Configure Validation
`MergeConfiguration`	Merging several definitions into one	Merge Multiple API Definitions
Filtering keys	Removing endpoints, properties, and parameters by tag	Filter your definition
Override keys	Replacing the description, contact, authentication, servers, and headers	Override parts of your definition

Filter your definition

Filtering keys remove parts of your definition by tag, so you can publish a subset of your API without keeping a separate copy of it. Add them at the top level of the metadata file.

Where tags come from

Item	Tag source
Endpoints (OpenAPI 2.0 and 3.x)	The operation's `tags`
Endpoints (RAML 1.0)	The `(x-tags)` annotation on the method
Schema properties	`x-tags` on the property
Parameters	`x-tags` on the parameter

Endpoints

Key	Type	What it does
`RemoveEndpointsWithTags`	array of strings	Removes endpoints that have any of these tags. Runs first.
`KeepEndpointsWithTags`	array of strings	Keeps only endpoints that have any of these tags. Runs after `RemoveEndpointsWithTags`.
`MaximumAllowedEndpoints`	integer	Removes endpoints beyond this number. Runs after the tag filters.

Removing endpoints also removes models and authentication schemes that only those endpoints used.

{
  "RemoveEndpointsWithTags": ["internal", "deprecated"],
  "KeepEndpointsWithTags": ["public"]
}

Properties and parameters

Key	Type	What it does
`RemoveSchemaPropertiesWithTags`	array of strings	Removes schema properties that have any of these tags, then removes schemas nothing uses any more. Examples are updated to match.
`RemoveParametersWithTags`	array of strings	Removes path, query, header, and cookie parameters that have any of these tags, then removes schemas nothing uses any more.

Removing schema properties can change your API in ways that are hard to spot. Removing a discriminator property breaks polymorphic schemas, a property removed from a parent is removed from its allOf children, oneOf and anyOf options can become indistinguishable, and descriptions or minProperties limits can stop matching the schema. Check the result before you publish it.

By default, removed properties are also removed from examples. To keep them, set the import setting RemoveUndeclaredPropertiesFromExample to false; they then show up as additional properties in your portal and generated samples.

Everything at once

RemoveInformationWithTags (array of strings) removes endpoints, schema properties, and parameters with these tags in one step. It's the same as setting RemoveEndpointsWithTags, RemoveSchemaPropertiesWithTags, and RemoveParametersWithTags to the same list.

{
  "RemoveInformationWithTags": ["internal"]
}

Override parts of your definition

Override keys replace parts of your definition with the values in the metadata file.

Overrides are for advanced use. Contact APIMatic support before you use them.

Description

Description (string) replaces the API description.

Contact

Key	Type	Description
`Contact.Name`	string	Contact name
`Contact.Url`	string	Contact URL
`Contact.Email`	string	Contact email

Authentication

Key	Type	Description
`Type`	string	Authentication type. See the values below.
`Parameters`	array of `{ Name, Description, DefaultValue }`	Authentication parameters
`Scopes`	array of `{ Name, Value, Description }`	OAuth 2.0 scopes. `Name` is a readable label and `Value` is the scope sent to the server.
`OAuth2AuthorizationServer`	string	Name of the server used as the base URL of the authorization endpoint
`AuthorizationUrl`	string	Path of the authorization endpoint
`OAuth2Server`	string	Name of the server used as the base URL of the token endpoint
`AccessTokenUrl`	string	Path of the token endpoint
`OAuth2ClientIdExample`	string	Example client ID
`OAuth2ClientSecretExample`	string	Example client secret
`OAuth2UsernameExample`	string	Example username
`OAuth2PasswordExample`	string	Example password

Type takes one of these values:

None · Basic · OAuth_v2_BearerToken · OAuth_v2_WebServerFlow · OAuth_v2_TwoLeggedFlow_ClientCredentials · OAuth_v2_ImplicitGrantFlow_UserAgent · OAuth_v2_Resource_Owner_Password · OAuth_v2_Password_Only · CustomQuery · CustomHeader · CustomField · JWT · CookieAuth

ServerConfiguration

Key	Type	Description
`DefaultEnvironment`	string	Environment used by default across the API
`DefaultServer`	string	Server used by default. Endpoints can set their own.
`Environments`	array	Each has `Name`, `Description`, and `Servers`, an array of `{ Name, Url }`
`Parameters`	array	Parameters used in server URLs. Each has `Name`, `Description`, `Type` (`String`, `Number`, `Number Enumeration`, or `String Enumeration`), and `DefaultValue`.

{
  "ServerConfiguration": {
    "DefaultEnvironment": "production",
    "DefaultServer": "default",
    "Environments": [
      {
        "Name": "production",
        "Servers": [{ "Name": "default", "Url": "https://api.example.com" }]
      }
    ],
    "Parameters": []
  }
}

AdditionalHeaders

AdditionalHeaders is an array of headers added to every request. Each has Name, Description, and DefaultValue.

Add the metadata fileCopy Anchor Link

Top-level sectionsCopy Anchor Link

Filter your definitionCopy Anchor Link

Where tags come fromCopy Anchor Link

EndpointsCopy Anchor Link

Properties and parametersCopy Anchor Link

Everything at onceCopy Anchor Link

Override parts of your definitionCopy Anchor Link

DescriptionCopy Anchor Link

ContactCopy Anchor Link

AuthenticationCopy Anchor Link

ServerConfigurationCopy Anchor Link

AdditionalHeadersCopy Anchor Link

On this page