--- updatedAt: 2026-04-05T12:27:38.000Z agentTools: siteIndex: https://docs.jfrog.com/llms.txt projectIndex: https://docs.jfrog.com/administration/llms.txt --- # Create a Federation Define a new Platform Federation on the Controller JPD. A federation specifies which Curation entities to synchronize and which Follower JPDs participate. **Prerequisites:** All Follower JPDs referenced in `target_jpd_ids` must already be added via the Add a Follower JPD API (`POST /pfed/api/v1/jpd`). The request body follows a fixed structure. Only the following fields are user-configurable: - **`name`** — A unique name for this federation. - **`description`** — A brief description of the use case. - **`connection_groups.source-jpd.target_jpd_ids`** — The list of Follower JPD IDs to include. The `connection_groups` key (`"source-jpd"`) and the `entities` list are fixed and must be provided exactly as shown in the example. **Fixed entity types (must all be included as-is):** - `catalog.customLabels` — Catalog custom labels - `xray.curationCondition` — Curation conditions - `xray.curationPkgType` — Curation package types - `xray.curationPolicy` — Curation policies **Security:** Requires admin privileges. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "JFrog Platform - Curation Federation API", "description": "Curation Federation APIs for synchronizing Curation entities across multiple JPDs in a Controller/Follower topology.\n\n**Authentication:** Access Tokens as bearer token in authorization header (Authorization: Bearer ``)\n\n**Security:** All APIs require admin privileges.\n", "version": "1.0.0", "contact": { "name": "JFrog Support" } }, "servers": [ { "url": "https://{jfrog_url}", "description": "JFrog Platform Server" } ], "tags": [ { "name": "Federations", "description": "APIs for creating, listing, retrieving, and deleting Platform Federations on the Controller JPD." } ], "security": [ { "AdminBearerAuth": [] } ], "paths": { "/pfed/api/v1/federations": { "post": { "tags": [ "Federations" ], "summary": "Create a Federation", "description": "Define a new Platform Federation on the Controller JPD. A federation specifies which Curation entities to synchronize and which Follower JPDs participate.\n\n**Prerequisites:** All Follower JPDs referenced in `target_jpd_ids` must already be added via the Add a Follower JPD API (`POST /pfed/api/v1/jpd`).\n\nThe request body follows a fixed structure. Only the following fields are user-configurable:\n- **`name`** — A unique name for this federation.\n- **`description`** — A brief description of the use case.\n- **`connection_groups.source-jpd.target_jpd_ids`** — The list of Follower JPD IDs to include.\n\nThe `connection_groups` key (`\"source-jpd\"`) and the `entities` list are fixed and must be provided exactly as shown in the example.\n\n**Fixed entity types (must all be included as-is):**\n- `catalog.customLabels` — Catalog custom labels\n- `xray.curationCondition` — Curation conditions\n- `xray.curationPkgType` — Curation package types\n- `xray.curationPolicy` — Curation policies\n\n**Security:** Requires admin privileges.\n", "operationId": "createFederation", "x-readme": { "code-samples": [ { "language": "curl", "name": "cURL", "code": "curl --location 'https://.jfrog.io/pfed/api/v1/federations' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ' \\\n--data '{\n \"name\": \"curation federation\",\n \"description\": \"manage curation over multisite architecture\",\n \"connection_groups\": {\n \"source-jpd\": {\n \"target_jpd_ids\": [\n \"follower_1\",\n \"follower_n\"\n ]\n }\n },\n \"entities\": [\n {\"type\": \"catalog.customLabels\"},\n {\"type\": \"xray.curationCondition\"},\n {\"type\": \"xray.curationPkgType\"},\n {\"type\": \"xray.curationPolicy\"}\n ]\n}'\n" } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFederationRequest" }, "example": { "name": "curation federation", "description": "manage curation over multisite architecture", "connection_groups": { "source-jpd": { "target_jpd_ids": [ "follower_1", "follower_n" ] } }, "entities": [ { "type": "catalog.customLabels" }, { "type": "xray.curationCondition" }, { "type": "xray.curationPkgType" }, { "type": "xray.curationPolicy" } ] } } } }, "responses": { "201": { "description": "Federation created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FederationDetails" }, "example": { "id": "fed-abc123", "name": "curation federation", "description": "manage curation over multisite architecture", "connection_groups": { "source-jpd": { "target_jpd_ids": [ "follower_1", "follower_n" ] } }, "entities": [ { "type": "catalog.customLabels" }, { "type": "xray.curationCondition" }, { "type": "xray.curationPkgType" }, { "type": "xray.curationPolicy" } ] } } } }, "400": { "description": "Bad Request — invalid JSON, missing required fields, or invalid entity type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized — missing or invalid admin token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden — insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict — a federation with this name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "securitySchemes": { "AdminBearerAuth": { "type": "http", "scheme": "bearer", "description": "Access Token with admin permissions as bearer token", "bearerFormat": "JWT" } }, "schemas": { "CreateFederationRequest": { "type": "object", "description": "Request body for creating a Platform Federation.\n\nOnly the following fields are user-configurable:\n- `name` — A unique name for this federation.\n- `description` — A brief description of the use case.\n- `connection_groups.source-jpd.target_jpd_ids` — The list of Follower JPD IDs.\n\nThe `connection_groups` key must be `\"source-jpd\"`. The `entities` array is fixed and\nmust be included exactly as shown — it cannot be modified or omitted.\n", "required": [ "name", "connection_groups", "entities" ], "properties": { "name": { "type": "string", "description": "A unique name for this federation within your subscription", "example": "curation federation" }, "description": { "type": "string", "description": "A brief description of the use case or feature supported by the federation", "example": "manage curation over multisite architecture" }, "connection_groups": { "type": "object", "description": "Connection group configuration. Must contain a single key `\"source-jpd\"` mapping\nto a connection group with the target Follower JPD IDs.\n" } } }, "ConnectionGroup": { "type": "object", "description": "Defines a connection group within a federation. Specifies the target Follower JPDs\nthat a source JPD will synchronize entities to.\n", "required": [ "target_jpd_ids" ], "properties": { "target_jpd_ids": { "type": "array", "description": "List of unique IDs of the Follower JPDs that participate in this connection group", "items": { "type": "string" }, "example": [ "follower_1", "follower_2" ] } } }, "EntityConfig": { "type": "object", "description": "Configuration for an entity type to be synchronized.\nEntity type names follow the format `.`.\n", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The entity type identifier in `.` format.\nSupported types:\n- `catalog.customLabels` — Catalog custom labels\n- `xray.curationCondition` — Curation conditions\n- `xray.curationPkgType` — Curation package types\n- `xray.curationPolicy` — Curation policies\n" } } }, "FederationDetails": { "type": "object", "description": "Full details of a federation configuration including connection groups and entity types", "properties": { "id": { "type": "string", "description": "The unique identifier of the federation (generated by the system)", "example": "fed-abc123" }, "name": { "type": "string", "description": "The unique name of the federation", "example": "curation federation" }, "description": { "type": "string", "description": "A brief description of the federation", "example": "manage curation over multisite architecture" }, "connection_groups": { "type": "object", "description": "Mapping of source JPD IDs to their connection group configurations", "additionalProperties": { "$ref": "#/components/schemas/ConnectionGroup" } }, "entities": { "type": "array", "description": "List of entity types synchronized by this federation", "items": { "$ref": "#/components/schemas/EntityConfig" } } } }, "ErrorResponse": { "type": "object", "description": "Standard error response", "properties": { "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid JSON format" }, "code": { "type": "integer", "description": "HTTP status code", "example": 400 } } } } }, "x-readme": { "explorer-enabled": false } } ```