AgileConfig/docs/api-v2.md

AgileConfig REST API v2

API v2 is available below /api/v2. It is additive: the existing /api/* endpoints remain available and keep their original contracts.

Authentication

• Administrative resources use HTTP Basic authentication with an AgileConfig administrator username and password.
• published-configurations uses the application ID and secret as the Basic authentication username and password.
• Service registration and heartbeat endpoints remain unauthenticated for compatibility with the existing service registry protocol. Service instance queries and deletion require administrator Basic authentication.

Administrative actions continue to enforce the same AgileConfig function permissions as their v1 equivalents.

Resources

Method	Path	Result
GET	/api/v2/applications	List applications
POST	/api/v2/applications	Create an application
GET	/api/v2/applications/{applicationId}	Get an application
PUT	/api/v2/applications/{applicationId}	Replace an application
DELETE	/api/v2/applications/{applicationId}	Delete an application
GET	/api/v2/applications/{applicationId}/environments/{environment}/configurations	List editable configurations
POST	/api/v2/applications/{applicationId}/environments/{environment}/configurations	Create a configuration
GET	/api/v2/applications/{applicationId}/environments/{environment}/configurations/{configurationId}	Get a configuration
PUT	/api/v2/applications/{applicationId}/environments/{environment}/configurations/{configurationId}	Replace a configuration
DELETE	/api/v2/applications/{applicationId}/environments/{environment}/configurations/{configurationId}	Mark a configuration for deletion
GET	/api/v2/applications/{applicationId}/environments/{environment}/published-configurations	Pull the effective published configuration
GET	/api/v2/applications/{applicationId}/environments/{environment}/releases	List releases
POST	/api/v2/applications/{applicationId}/environments/{environment}/releases	Publish pending changes
GET	/api/v2/applications/{applicationId}/environments/{environment}/releases/{releaseId}	Get a release
POST	/api/v2/applications/{applicationId}/environments/{environment}/releases/rollbacks	Roll back to a release
GET	/api/v2/nodes	List cluster nodes
POST	/api/v2/nodes	Add a cluster node
GET	/api/v2/nodes/{nodeId}	Get a cluster node
DELETE	/api/v2/nodes/{nodeId}	Delete a cluster node
GET	/api/v2/service-instances?status={Healthy|Unhealthy}	List or filter service instances
POST	/api/v2/service-instances	Register or refresh a service instance
GET	/api/v2/service-instances/{serviceInstanceId}	Get a service instance
DELETE	/api/v2/service-instances/{serviceInstanceId}	Unregister a service instance
PUT	/api/v2/service-instances/{serviceInstanceId}/heartbeat	Record a heartbeat

Node IDs are opaque URL-safe values returned by the API. Clients should not construct them from node addresses.

HTTP semantics

• Creation returns 201 Created, the created representation, and a Location header. Re-registering an existing service instance returns 200 OK because the existing resource is updated.
• Successful deletion and rollback return 204 No Content.
• Missing resources return 404 Not Found; identifier/key conflicts return 409 Conflict.
• Validation and domain errors use application/problem+json (ProblemDetails). Authentication and permission failures retain the server's existing 403 Forbidden behavior.
• Published configuration responses include ETag and X-Publish-Timeline-Id. Sending the ETag in If-None-Match returns 304 Not Modified when the published version has not changed.

Deleting an already published configuration removes it from the v2 editable resource view immediately, while the previous published value remains available to application clients until the pending deletion is released.