> ## Documentation Index > Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt > Use this file to discover all available pages before exploring further. # Refresh a protocol from its URL > Fetches the protocol from its stored URL and stores the document as the next revision when it changed and every check passes, including the compatibility of every backend that references the protocol. Redirects are not followed — the URL must answer 200 with the JSON document. With `dry_run`, nothing is written. ## OpenAPI ````yaml /products/link/openapi.yaml post /api/admin/protocols/{id}/refresh openapi: 3.0.0 info: description: >- Admin API for managing Link protocols and backends (Bundled and Standalone editions). title: Link API version: '1.0' servers: - url: https://{instance}.{env}.on-hellgate.cloud description: Managed instance of Link variables: instance: default: my-instance description: Your unique instance slug, provided during onboarding. env: default: eu1 description: Deployment environment (currently eu1). security: [] tags: [] paths: /api/admin/protocols/{id}/refresh: post: tags: - Protocols summary: Refresh a protocol from its URL description: >- Fetches the protocol from its stored URL and stores the document as the next revision when it changed and every check passes, including the compatibility of every backend that references the protocol. Redirects are not followed — the URL must answer 200 with the JSON document. With `dry_run`, nothing is written. operationId: protocols_refresh parameters: - description: Protocol local ID in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ProtocolRefreshRequest' examples: dry_run: summary: Check for an update without writing value: dry_run: true refresh: summary: Refresh and store the update value: dry_run: false description: Refresh options required: false responses: '200': content: application/json: schema: $ref: '#/components/schemas/ProtocolRefreshResult' example: status: update_available dry_run: true protocol: id: c4a1f2d0-5b3e-4f6a-8d29-1e7b9c0a2d43 local_id: specter-v1 url: https://developer.hellgate.io/protocols/specter/v1 name: Specter v1 version: 1.0.0 revision: 1 inserted_at: '2026-04-02T10:15:00Z' updated_at: '2026-04-02T10:15:00Z' description: Refresh result '401': content: application/json: schema: $ref: '#/components/schemas/Unauthorized' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/Forbidden' description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/NotFound' description: Not found '409': content: application/json: schema: $ref: '#/components/schemas/Error' examples: protocol_id_changed: summary: The fetched document's $id changed value: classifier: PROTOCOL_ID_CHANGED code: 409 message: The fetched document's $id does not match the protocol URL refresh_conflict: summary: A concurrent refresh finished first value: classifier: REFRESH_CONFLICT code: 409 message: The protocol changed during the refresh; retry description: $id changed or concurrent refresh '422': content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationErrors' - $ref: '#/components/schemas/Error' examples: incompatible_backend: summary: A backend no longer fits the new document value: classifier: VALIDATION_ERROR code: 422 validation_errors: - message: action 'assess' is missing required variant 'pan' path: backends.acme-risk fetch_failed: summary: The URL could not be fetched value: classifier: FETCH_FAILED code: 422 message: 'Failed to fetch protocol: HTTP 308' description: Validation, fetch or schema error '503': content: application/json: schema: $ref: '#/components/schemas/Error' example: classifier: AUDIT_UNAVAILABLE code: 503 message: The change could not be audited and was not applied; retry description: Audit unavailable callbacks: {} security: - bearerAuth: [] components: schemas: ProtocolRefreshRequest: description: Options of a protocol refresh. properties: dry_run: default: false description: Run every check and report `update_available` without writing. type: boolean title: ProtocolRefreshRequest type: object ProtocolRefreshResult: description: Outcome of a protocol refresh. properties: dry_run: example: true type: boolean protocol: $ref: '#/components/schemas/ProtocolSummary' status: description: >- `unchanged`: the URL serves the stored document. `update_available`: a dry run found a changed document that passes every check. `updated`: the changed document was stored as the next revision. enum: - unchanged - update_available - updated example: update_available type: string required: - status - dry_run - protocol title: ProtocolRefreshResult type: object Unauthorized: description: No valid authentication was provided. example: classifier: UNAUTHORIZED code: 401 message: No valid means of authentication was provided properties: classifier: enum: - UNAUTHORIZED type: string code: enum: - 401 type: integer message: type: string required: - classifier - code - message title: Unauthorized type: object Forbidden: description: The token lacks the scope required for this operation. example: classifier: FORBIDDEN code: 403 message: Not allowed to access this resource or feature properties: classifier: enum: - FORBIDDEN type: string code: enum: - 403 type: integer message: type: string required: - classifier - code - message title: Forbidden type: object NotFound: description: The requested resource does not exist. example: classifier: NOT_FOUND code: 404 message: The requested resource does not exist properties: classifier: enum: - NOT_FOUND type: string code: enum: - 404 type: integer message: type: string required: - classifier - code - message title: NotFound type: object Error: description: Generic error response. properties: classifier: type: string code: type: integer message: type: string required: - classifier - code - message title: Error type: object ValidationErrors: example: classifier: VALIDATION_ERROR code: 422 validation_errors: - message: must be a positive integer path: limit description: Response shape for request validation failures. properties: classifier: example: VALIDATION_ERROR type: string code: example: 422 type: integer validation_errors: items: properties: message: example: url is required type: string path: example: url nullable: true type: string type: object type: array required: - classifier - code - validation_errors title: ValidationErrors type: object ProtocolSummary: description: Summary of an imported or created protocol. properties: id: example: c4a1f2d0-5b3e-4f6a-8d29-1e7b9c0a2d43 format: uuid type: string inserted_at: example: '2026-04-02T10:15:00Z' format: date-time type: string local_id: example: specter-v1 type: string name: example: Specter v1 type: string revision: description: >- Starts at 1 and grows by one with every refresh that stores a new document. example: 1 minimum: 1 type: integer updated_at: example: '2026-04-02T10:15:00Z' format: date-time type: string url: example: https://developer.hellgate.io/protocols/specter/v1 type: string version: example: 1.0.0 type: string required: - id - local_id - url - name - version - revision - inserted_at - updated_at title: ProtocolSummary type: object securitySchemes: bearerAuth: bearerFormat: JWT scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.