Create Domain API
POST /obp/v7.0.0/management/banks/BANK_ID/domain-apis
OBPv7.0.0-createDomainApi Roles: CanCreateDomainApi(per bank) DynamicAPI
Publish the Dynamic Entities and Dynamic Resource Docs of a space under a base path of its own.
A Domain API publishes the Dynamic Entities and Dynamic Resource Docs (Dynamic Queries included) of one
space under a base path of its own, without OBP's own URL structure in front of them: with the base path
carbon-registry/v1 over the system space, /carbon-registry/v1/activity answers what
/obp/v7.0.0/banks/SYS/dynamic-entities/activity answers, and /carbon-registry/v1/openapi.yaml (or
openapi.json) is its OpenAPI document. It only renames: every call runs the same authentication, Roles
and access checks as the OBP URL, and a Dynamic Entity record response leaves out bank_id.
BANK_ID is the space: a bank's id, or SYS for the system space. The Role is checked at that BANK_ID.
is_publicly_discoverable says whether anyone, without logging in, may find the Domain API through
GET /obp/v7.0.0/banks/BANK_ID/domain-apis. It is false when left out on create and keeps its current
value when left out on update. It only controls that listing: the calls under the base path and the
OpenAPI document are served the same either way.
base_path is two to five segments of lowercase letters, digits, hyphens and dots, ending with the
major version as vN, and must not overlap another Domain API's. version is the full semantic
version, MAJOR.MINOR.PATCH, whose MAJOR is the N of the base path: a compatible change edits version
and leaves every URL alone, and a breaking change gets a new Domain API with a new base path.
A Domain API is refused while two endpoints of its space are ambiguous with each other under it: a
Dynamic Resource Doc whose path starts with a path variable, with the name of one of the space's
Dynamic Entities or with a segment the Dynamic Entity URLs or the documentation use (my, public,
community, openapi.json, openapi.yaml), or two docs of one verb that would match one request.
Creating or changing a Dynamic Entity or Dynamic Resource Doc that would cause one is refused in
every space, so this only happens to a space that held one before that rule.
On this instance a change is seen at once by the node that made it, and by the others within 10 seconds.
For more information see here
User Authentication is Required. The User must be logged in. The Application must also be authenticated.
URL Parameters:
BANK_ID: gh.29.uk
JSON request body fields (5)
- base_path
- base_path
- title
- Dr.
- version
- description
- Description of the object. Maximum length is 2000. It can be any characters here.
- is_publicly_discoverable
- is_publicly_discoverable
JSON response body fields (12)
- bank_id
- gh.29.uk
- base_path
- base_path
- created_at
- created_at
- created_by_user_id
- description
- Description of the object. Maximum length is 2000. It can be any characters here.
- domain_api_id
- domain_api_id
- is_publicly_discoverable
- is_publicly_discoverable
- openapi_url
- openapi_url
- title
- Dr.
- updated_at
- updated_at
- url
- http://www.example.com/id-docs/123/image.png
- version
Example request body
{
"base_path": "carbon-registry/v1",
"version": "1.0.0",
"title": "Open Carbon Registry API",
"description": "Activities and land parcels of the registry.",
"is_publicly_discoverable": true
}Example success response
{
"domain_api_id": "5f4a1c8e-2b7d-4e9a-9c3f-1d2e3f4a5b6c",
"bank_id": "SYS",
"base_path": "carbon-registry/v1",
"version": "1.0.0",
"title": "Open Carbon Registry API",
"description": "Activities and land parcels of the registry.",
"is_publicly_discoverable": true,
"url": "https://api.example.org/carbon-registry/v1",
"openapi_url": "https://api.example.org/carbon-registry/v1/openapi.yaml",
"created_by_user_id": "9ca9a7e4-6d02-40e3-a129-0b2bf89de9b1",
"created_at": "2026-10-21T01:45:41Z",
"updated_at": "2026-10-21T01:45:41Z"
}Possible errors (10)
- OBP-30001: Bank not found. Please specify a valid value for BANK_ID.
- OBP-20001: User not logged in. Authentication is required!
- OBP-20006: User is missing one or more roles:
- OBP-10001: Incorrect json format.
- OBP-09026: Invalid base_path. It must be two to five segments of lowercase letters, digits, hyphens or dots, separated by /, with no leading or trailing /, ending with the major version as vN (for example carbon-registry/v1), and its first segment must not be one OBP itself serves:
- OBP-09028: Invalid version. It must be a semantic version, MAJOR.MINOR.PATCH (for example 1.0.0), whose MAJOR equals the N of the vN that ends base_path.
- OBP-09030: Invalid title or description. title must be 1 to 255 characters and description at most 2000.
- OBP-09027: Another Domain API already uses this base_path, or one that starts with it or that it starts with:
- OBP-09031: Endpoints of this space are ambiguous with each other, so a Domain API cannot publish the space until one of them is renamed or removed:
- OBP-50000: Unknown Error.