New Endpoint
Developmentnew-endpointNew Endpoint is an Agent Skill for development published in the fleetdm/fleet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Scaffold a new Fleet API endpoint with request/response structs, endpoint function, service method, datastore interface, handler registration, and test stubs.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/fleetdm/fleet/blob/HEAD/.claude/skills/new-endpoint/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/new-endpoint, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Scaffold a New Fleet API Endpoint
Create a new API endpoint for: $ARGUMENTS
Process
1. Gather Requirements
- Resource name and HTTP method (GET/POST/PATCH/DELETE)
- URL path (e.g.,
/api/_version_/fleet/resource) - Request body fields (if any)
- Response body fields
- Which API version (use
StartingAtVersion("2022-04")for new endpoints) - Does it need a datastore method?
2. Read Reference Patterns
Read server/service/vulnerabilities.go for the canonical request/response/endpoint pattern:
- Request struct with json tags
- Response struct with
Err errorfield andError()method - Endpoint function with
(ctx, request, svc)signature
Read server/service/handler.go to find where to register the new endpoint.
3. Create Request/Response Structs
type myResourceRequest struct {
ID uint `url:"id"`
Name string `json:"name"`
}
type myResourceResponse struct {
Resource *fleet.Resource `json:"resource,omitempty"`
Err error `json:"error,omitempty"`
}
func (r myResourceResponse) Error() error { return r.Err }
4. Create Endpoint Function
func myResourceEndpoint(ctx context.Context, request interface{}, svc fleet.Service) (fleet.Errorer, error) {
req := request.(*myResourceRequest)
result, err := svc.MyResource(ctx, req.ID)
if err != nil {
return myResourceResponse{Err: err}, nil
}
return myResourceResponse{Resource: result}, nil
}
5. Add Service Interface Method
In server/fleet/service.go, add the method to the Service interface.
6. Implement Service Method
In the appropriate server/service/*.go file:
- Start with
svc.authz.Authorize(ctx, &fleet.Entity{}, fleet.ActionRead) - Implement business logic
- Wrap errors with
ctxerr.Wrap
7. Add Datastore Interface Method (if needed)
In server/fleet/datastore.go, add the method to the Datastore interface.
8. Register in handler.go
ue.StartingAtVersion("2022-04").GET("/api/_version_/fleet/resource", myResourceEndpoint, myResourceRequest{})
9. Create Test Stubs
- Unit test with mock datastore in
server/service/*_test.go - Integration test stub if it touches the database
10. Verify
- Run
go build ./...to check compilation - Run
go test ./server/service/to check mocks are satisfied