--- title: "Update API Spec" url: "https://us-prod.jeffyongtaotang.com/apis/konnect-service-catalog-1/versions/cdbef9b7-686c-4189-bbc8-55c727a972e8/operations/update-catalog-service-api-spec" --- > Full API specification: https://us-prod.jeffyongtaotang.com/apis/konnect-service-catalog-1/versions/cdbef9b7-686c-4189-bbc8-55c727a972e8.md # Update API Spec `PATCH` `/catalog-services/{serviceId}/api-specs/{apiSpecId}` Operation ID: `update-catalog-service-api-spec` Updates the API spec for the given service. ## Path parameters - `serviceId` (string, required) - The `id` of the service. - `apiSpecId` (string, required) - The `id` of the service. ## Request body (required) Content types: `application/json` ## Responses - `200` - A response containing a single API spec. - `400` - Bad Request - `401` - Unauthorized - `403` - Forbidden - `404` - Not Found ## OpenAPI definition ```yaml openapi: 3.0.3 info: title: Konnect Service Catalog version: 1.3.0 servers: - url: https://us.api.konghq.com/v1 description: United-States Production region - url: https://eu.api.konghq.com/v1 description: Europe Production region - url: https://au.api.konghq.com/v1 description: Australia Production region - url: https://me.api.konghq.com/v1 description: Middle-East Production region - url: https://in.api.konghq.com/v1 description: India Production region - url: https://sg.api.konghq.com/v1 description: Singapore Production region paths: /catalog-services/{serviceId}/api-specs/{apiSpecId}: parameters: - schema: type: string example: 7f9fd312-a987-4628-b4c5-bb4f4fddd5f7 name: serviceId in: path required: true description: The `id` of the service. - schema: type: string example: 7f9fd312-a987-4628-b4c5-bb4f4fddd5f7 name: apiSpecId in: path required: true description: The `id` of the service. patch: x-unstable: true x-internal: true summary: Update API Spec operationId: update-catalog-service-api-spec description: Updates the API spec for the given service. requestBody: $ref: "#/components/requestBodies/UpdateCatalogServiceApiRequest" responses: "200": $ref: "#/components/responses/CatalogServiceApiSpecResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": $ref: "#/components/responses/NotFound" tags: - Catalog Service API Specs security: - konnectAccessToken: [] - personalAccessToken: [] - systemAccountAccessToken: [] components: requestBodies: UpdateCatalogServiceApiRequest: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateCatalogServiceApiSpec" examples: Update Service API: $ref: "#/components/examples/UpdateServiceApiPayload" responses: CatalogServiceApiSpecResponse: description: A response containing a single API spec. content: application/json: schema: $ref: "#/components/schemas/CatalogServiceApiSpec" examples: Url: $ref: "#/components/examples/ServiceApiUrlResponse" Raw: $ref: "#/components/examples/ServiceApiRawResponse" Integration: $ref: "#/components/examples/CreateServiceApiIntegrationResponse" Resource: $ref: "#/components/examples/CreateServiceApiResourceResponse" BadRequest: description: Bad Request content: application/problem+json: schema: $ref: "#/components/schemas/BadRequestError" Unauthorized: description: Unauthorized content: application/problem+json: schema: $ref: "#/components/schemas/UnauthorizedError" examples: UnauthorizedExample: $ref: "#/components/examples/UnauthorizedExample" Forbidden: description: Forbidden content: application/problem+json: schema: $ref: "#/components/schemas/ForbiddenError" examples: UnauthorizedExample: $ref: "#/components/examples/ForbiddenExample" NotFound: description: Not Found content: application/problem+json: schema: $ref: "#/components/schemas/NotFoundError" examples: NotFoundExample: $ref: "#/components/examples/NotFoundExample" schemas: UpdateCatalogServiceApiSpec: type: object additionalProperties: false properties: name: type: string description: The name of the API minLength: 1 maxLength: 120 example: Pet Store description: type: string description: The description of the API nullable: true maxLength: 2048 example: > A sample API that uses a pet store as an example to demonstrate features in the OpenAPI specification provider: title: CreateApiSpecProvider description: > Represents the provider, or source, of an API specs. Note that `provider` cannot be patched for API specs that are bound to a resource. Trying to do so will result in a 400 response. oneOf: - $ref: "#/components/schemas/UrlApiSpecProvider" - $ref: "#/components/schemas/RawApiSpecProviderPayload" - $ref: "#/components/schemas/IntegrationApiSpecProviderPayload" - $ref: "#/components/schemas/ResourceBoundIntegrationApiSpecProviderPayload" CatalogServiceApiSpec: type: object required: - id - service_id - name - description - resource_id - provider - created_at - updated_at properties: id: type: string format: uuid example: eadb88fe-e8eb-45c2-9591-dc783f93f29b description: The API spec ID service_id: type: string format: uuid example: 7f9fd312-a987-4628-b4c5-bb4f4fddd5f7 description: The ID of the service the API spec is associated to. name: type: string description: The name of the API minLength: 1 maxLength: 120 example: Pet Store description: type: string description: The description of the API. nullable: true maxLength: 2048 example: > A sample API that uses a pet store as an example to demonstrate features in the OpenAPI specification. resource_id: type: string nullable: true description: > The ID of the Resource that is bound to the API spec. Only set when the given `provider.type` requires a 1-to-1 mapping between Resource and API Spec. example: IqkHvMdyHukxcwAs provider: title: ApiSpecProvider description: Represents the provider, or source, of API spec contents. x-convert-oneOf: true anyOf: - $ref: "#/components/schemas/UrlApiSpecProvider" - $ref: "#/components/schemas/RawApiSpecProvider" - $ref: "#/components/schemas/IntegrationApiSpecProvider" - $ref: "#/components/schemas/ResourceBoundIntegrationApiSpecProvider" created_at: $ref: "#/components/schemas/CreatedAt" updated_at: $ref: "#/components/schemas/UpdatedAt" BadRequestError: allOf: - $ref: "#/components/schemas/BaseError" - type: object required: - invalid_parameters properties: invalid_parameters: $ref: "#/components/schemas/InvalidParameters" UnauthorizedError: allOf: - $ref: "#/components/schemas/BaseError" - type: object properties: status: example: 401 title: example: Unauthorized type: example: https://httpstatuses.com/401 instance: example: kong:trace:1234567890 detail: example: Invalid credentials ForbiddenError: allOf: - $ref: "#/components/schemas/BaseError" - type: object properties: status: example: 403 title: example: Forbidden type: example: https://httpstatuses.com/403 instance: example: kong:trace:1234567890 detail: example: Forbidden NotFoundError: allOf: - $ref: "#/components/schemas/BaseError" - type: object properties: status: example: 404 title: example: Not Found type: example: https://httpstatuses.com/404 instance: example: kong:trace:1234567890 detail: example: Not found UrlApiSpecProvider: type: object required: - type - config properties: type: type: string enum: - url config: type: object required: - url properties: url: type: string format: uri description: | Public URL that resolves to the raw API spec contents. Supported formats are JSON and YAML. example: https://api.petstore.com/v3/openapi.json RawApiSpecProviderPayload: type: object properties: type: type: string enum: - raw config: title: RawApiSpecProviderConfig type: object additionalProperties: false properties: contents: type: string description: | Raw API spec file contents. Supports JSON or YAML format. Raw specs have a maximum size limit of 8mb. example: | {"openapi":"3.0.0","info":{"version":"1.0.0","title":"Swagger Petstore","license":{"name":"MIT"}},"servers":[{"url":"http://petstore.swagger.io/v1"}],"paths":{"/pets":{"get":{"summary":"List all pets","operationId":"listPets","tags":["pets"],"parameters":[{"name":"limit","in":"query","description":"How many items to return at one time (max 100)","required":false,"schema":{"type":"integer","maximum":100,"format":"int32"}}],"responses":{"200":{"description":"A paged array of pets","headers":{"x-next":{"description":"A link to the next page of responses","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pets"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a pet","operationId":"createPets","tags":["pets"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}}},"required":true},"responses":{"201":{"description":"Null response"},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pets/{petId}":{"get":{"summary":"Info for a specific pet","operationId":"showPetById","tags":["pets"],"parameters":[{"name":"petId","in":"path","required":true,"description":"The id of the pet to retrieve","schema":{"type":"string"}}],"responses":{"200":{"description":"Expected response to a valid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pet"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Pet":{"type":"object","required":["id","name"],"properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"tag":{"type":"string"}}},"Pets":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Pet"}},"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}}} required: - contents required: - type - config IntegrationApiSpecProviderPayload: description: > API spec provider registered by a catalog integration. Integrations can function as API spec providers where they register a globally unique `type` and config schema which defines the shape of `config`. Consult integration documentation to learn more about available API spec providers. type: object required: - type - config - integration_instance properties: type: type: string description: The globally unique API spec provider type that is registered by a given catalog integration. minLength: 1 maxLength: 120 example: swaggerhub_api_version config: type: object additionalProperties: true minProperties: 1 description: JSON object containing values as defined by integration provider's config schema. example: owner: petco api: pet_store version: v3 integration_instance: type: string description: The integration instance id or name ResourceBoundIntegrationApiSpecProviderPayload: description: > API spec provider registered by a catalog integration. These providers differ from `IntegrationApiSpecProvider` in that they denote a binding relationship between a resource type and the API spec. This means that the API Spec will automatically be created/deleted for/from a service as resources of the given type are mapped/unmapped. Consult integration documentation to learn more about available API spec providers. type: object required: - type - config properties: type: type: string description: > The globally unique API spec provider type that is registered by a given catalog integration. Resource-bound providers create a 1-to-1 mapping between a resource type and the API Spec. minLength: 1 maxLength: 120 config: type: object required: - resource_id properties: resource_id: type: string description: ID of the associated Resource the API spec is bound to. example: IqkHvMdyHukxcwAs RawApiSpecProvider: type: object required: - type - config properties: type: type: string enum: - raw config: type: object additionalProperties: false minProperties: 0 maxProperties: 0 IntegrationApiSpecProvider: description: > API spec provider registered by a catalog integration. Integrations can function as API spec providers where they register a globally unique `type` and config schema which defines the shape of `config`. Consult integration documentation to learn more about available API spec providers. type: object required: - type - config - integration properties: type: type: string description: The globally unique API spec provider type that is registered by a given catalog integration. minLength: 1 maxLength: 120 example: swaggerhub_api_version config: type: object additionalProperties: true minProperties: 1 description: JSON object containing values as defined by integration provider's config schema. example: owner: petco api: pet_store version: v3 integration: $ref: "#/components/schemas/IntegrationRef" ResourceBoundIntegrationApiSpecProvider: description: > API spec provider registered by a catalog integration. These providers differ from `IntegrationApiSpecProvider` in that they denote a binding relationship between a resource type and the API spec. This means that the API Spec will automatically be created/deleted for/from a service as resources of the given type are mapped/unmapped. Consult integration documentation to learn more about available API spec providers. type: object required: - type - config - integration properties: type: type: string description: > The globally unique API spec provider type that is registered by a given catalog integration. Resource-bound providers create a 1-to-1 mapping between a resource type and the API Spec. minLength: 1 maxLength: 120 config: type: object required: - resource_id properties: resource_id: type: string description: ID of the associated Resource the API spec is bound to. example: IqkHvMdyHukxcwAs integration: $ref: "#/components/schemas/IntegrationRef" CreatedAt: type: string format: date-time example: 2022-11-04T20:10:06.927Z description: An ISO-8601 timestamp representation of entity creation date. readOnly: true x-speakeasy-param-suppress-computed-diff: true UpdatedAt: type: string format: date-time example: 2022-11-04T20:10:06.927Z description: An ISO-8601 timestamp representation of entity update date. readOnly: true x-speakeasy-param-suppress-computed-diff: true BaseError: type: object title: Error description: standard error required: - status - title - instance - detail properties: status: type: integer description: > The HTTP status code of the error. Useful when passing the response body to child properties in a frontend UI. Must be returned as an integer. readOnly: true title: type: string description: | A short, human-readable summary of the problem. It should not change between occurences of a problem, except for localization. Should be provided as "Sentence case" for direct use in the UI. readOnly: true type: type: string description: The error type. readOnly: true instance: type: string description: | Used to return the correlation ID back to the user, in the format kong:trace:. This helps us find the relevant logs when a customer reports an issue. readOnly: true detail: type: string description: > A human readable explanation specific to this occurence of the problem. This field may contain request/entity data to help the user understand what went wrong. Enclose variable values in square brackets. Should be provided as "Sentence case" for direct use in the UI. readOnly: true InvalidParameters: type: array nullable: false uniqueItems: true minItems: 1 description: invalid parameters items: oneOf: - $ref: "#/components/schemas/InvalidParameterStandard" - $ref: "#/components/schemas/InvalidParameterMinimumLength" - $ref: "#/components/schemas/InvalidParameterMaximumLength" - $ref: "#/components/schemas/InvalidParameterChoiceItem" - $ref: "#/components/schemas/InvalidParameterDependentItem" IntegrationRef: type: object description: Short-hand descriptor of an integration installed within the catalog. required: - name - display_name - instance properties: name: type: string example: gateway-manager display_name: type: string example: gateway-manager instance: $ref: "#/components/schemas/IntegrationInstanceRef" InvalidParameterStandard: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: $ref: "#/components/schemas/InvalidRules" source: type: string example: body reason: type: string example: is a required field readOnly: true required: - field - reason InvalidParameterMinimumLength: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: description: invalid parameters rules type: string readOnly: true nullable: false enum: - min_length - min_digits - min_lowercase - min_uppercase - min_symbols - min_items - min minimum: type: integer example: 8 source: type: string example: body reason: type: string example: must have at least 8 characters readOnly: true required: - field - reason - rule - minimum InvalidParameterMaximumLength: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: description: invalid parameters rules type: string readOnly: true nullable: false enum: - max_length - max_items - max maximum: type: integer example: 8 source: type: string example: body reason: type: string example: must not have more than 8 characters readOnly: true required: - field - reason - rule - maximum InvalidParameterChoiceItem: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: description: invalid parameters rules type: string readOnly: true nullable: false enum: - enum reason: type: string example: is a required field readOnly: true choices: type: array uniqueItems: true readOnly: true nullable: false minItems: 1 items: {} source: type: string example: body required: - field - reason - rule - choices InvalidParameterDependentItem: type: object additionalProperties: false properties: field: type: string example: name readOnly: true rule: description: invalid parameters rules type: string readOnly: true nullable: true enum: - dependent_fields reason: type: string example: is a required field readOnly: true dependents: type: array uniqueItems: true nullable: true items: {} readOnly: true source: type: string example: body required: - field - rule - reason - dependents IntegrationInstanceRef: type: object description: Short-hand descriptor of an integration instance. required: - id - name - display_name properties: id: type: string format: uuid example: 772b9caf-ddbc-4f4f-8aa4-8dfbbe420351 description: The integration instance ID. name: type: string description: > The machine name of the integration instance that uniquely identifies it within the catalog. pattern: ^[0-9a-z.-]+$ example: aws-lambda-prod display_name: type: string description: The display name of the integration instance. example: AWS (prod) InvalidRules: description: invalid parameters rules type: string readOnly: true nullable: true enum: - required - is_array - is_base64 - is_boolean - is_date_time - is_integer - is_null - is_number - is_object - is_string - is_uuid - is_fqdn - is_arn - unknown_property - missing_reference - is_label - matches_regex - invalid - is_supported_network_availability_zone_list - is_supported_network_cidr_block - is_supported_provider_region - type examples: UpdateServiceApiPayload: value: name: api-spec-name description: API Spec Description ServiceApiUrlResponse: value: id: 8e3882ff-ad0f-4690-a5a7-c69323084109 service_id: 204d85d2-1bb9-4864-842f-6d97a7cbca2c resource_id: null name: spec-from-url description: API Spec from URL created_at: 2025-05-01T00:00:00.000000Z updated_at: 2025-05-01T00:00:00.000000Z provider: type: url config: url: https://my-company.com/api-specs/openapi.yaml ServiceApiRawResponse: value: id: a237f806-e9ea-4c56-89f5-ab92b5e19913 service_id: 204d85d2-1bb9-4864-842f-6d97a7cbca2c resource_id: null name: spec-from-raw description: API Spec from Raw created_at: 2025-05-01T00:00:00.000000Z updated_at: 2025-05-01T00:00:00.000000Z provider: type: raw config: {} CreateServiceApiIntegrationResponse: value: id: 3a276c30-f209-44dc-9814-df291bc94950 service_id: 204d85d2-1bb9-4864-842f-6d97a7cbca2c name: spec-from-integration description: API Spec from Integration resource_id: null created_at: 2025-05-01T00:00:00.000000Z updated_at: 2025-05-01T00:00:00.000000Z provider: type: github_repo config: repo: MyOrganization owner: MyService spec_path: openapi.yaml integration: name: github display_name: GitHub instance: id: bd24cfdd-619e-4696-b58d-a9ea49e5ea39 name: github display_name: GitHub CreateServiceApiResourceResponse: value: id: e0928050-20d0-448f-947d-624d9901947e service_id: 204d85d2-1bb9-4864-842f-6d97a7cbca2c resource_id: ok-qTDpuiQp7DWK0 name: spec-from-resource description: API Spec from Resource created_at: 2025-05-01T00:00:00.000000Z updated_at: 2025-05-01T00:00:00.000000Z provider: type: swaggerhub_api_version config: resource_id: ok-qTDpuiQp7DWK0 integration: name: swaggerhub display_name: SwaggerHub instance: id: e0f2388b-2efe-42a3-a9e4-86f12d3e8c77 name: swaggerhub-internal display_name: SwaggerHub (Internal) UnauthorizedExample: value: status: 401 title: Unauthorized instance: kong:trace:8347343766220159418 detail: Unauthorized ForbiddenExample: value: status: 403 title: Forbidden instance: kong:trace:2723154947768991354 detail: You do not have permission to perform this action NotFoundExample: value: status: 404 title: Not Found instance: kong:trace:6816496025408232265 detail: Not Found securitySchemes: konnectAccessToken: type: http scheme: bearer bearerFormat: JWT description: > The Konnect access token is meant to be used by the Konnect dashboard and the decK CLI authenticate with. personalAccessToken: type: http scheme: bearer bearerFormat: Token description: > The personal access token is meant to be used as an alternative to basic-auth when accessing Konnect via APIs. You can generate a Personal Access Token (PAT) from the [personal access token page](https://cloud.konghq.com/global/account/tokens/) in the Konnect dashboard. The PAT token must be passed in the header of a request, for example: `curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer kpat_xgfT...'` systemAccountAccessToken: type: http scheme: bearer bearerFormat: Token description: > The system account access token is meant for automations and integrations that are not directly associated with a human identity. You can generate a system account Access Token by creating a system account and then obtaining a system account access token for that account. The access token must be passed in the header of a request, for example: `curl -X GET 'https://global.api.konghq.com/v2/users/' --header 'Authorization: Bearer spat_i2Ej...'` ```