Skip to main content

Endpoint Registration

When you discover a new API endpoint, you MUST delegate its registration to the register-endpoint subagent. You do NOT create endpoints directly — the subagent investigates it thoroughly, documents it with full quality standards, and registers it. A P4 vulnerability recon task is automatically created for every registered endpoint.

The Registration Process​

The subagent follows this process for every endpoint. Understanding these steps helps you provide better context when delegating.

Step 1: Service Context & Duplicate Check​

The subagent looks up the parent service to understand the technology stack, auth mechanism, and existing endpoints. If a duplicate exists, it stops early. What you should provide: service_id (or service name so it can look it up).

Step 2: Unauthenticated Probing​

The subagent curls the endpoint without auth to observe the baseline behavior: what status code comes back, what error format the API uses, what server headers leak technology info. This reveals whether auth is required and what the rejection looks like. What you should provide: any observations you already made (e.g., "I saw a 401 when I hit this").

Step 3: Authenticated Probing​

If auth info is available, the subagent curls with credentials to see the real response: what data comes back, what fields are in the response, whether there's PII or sensitive data. It also probes with invalid inputs to trigger error messages that reveal the expected request schema. What you should provide: actual auth tokens, cookies, or API keys that work. Include the real values — the subagent needs them to make requests.

Step 4: Parameter & Header Discovery​

From all probing, the subagent maps:

  • Request headers: auth headers, content-type, CSRF tokens, custom headers
  • Parameters: path params, query params, request body fields with types
  • Response headers: rate limits, cookies, CORS, server fingerprinting

Each parameter and header gets a description explaining its purpose, not just restating the name.

Step 5: Documentation & Registration​

The subagent compiles everything into:

  • description: What the endpoint does, what data it handles, auth requirements, rate limits, security observations (min 50 chars, typically 2-4 sentences)
  • headers: List of request headers with name, example value, required flag, description
  • openapi_schema: Parameters, request body schema, and response definitions
  • example_calls: Real curl commands with real responses (headers + body)

Then calls create_endpoint which validates quality and auto-creates the P4 task.

Quality Standards​

These are enforced by the create_endpoint tool — submissions that don't meet them are rejected:

Description (min 50 characters) must answer:

  • What does this endpoint do? (functional purpose)
  • What data does it handle? (PII, financial, admin?)
  • What auth is required? (Bearer, cookie, API key, none?)
  • Any notable behavior? (rate limits, pagination, caching?)

GOOD: "Full-text user search returning paginated results including PII (email, display_name, role). Requires Bearer JWT auth. Rate-limited to 100 req/min. Response includes total count enabling user enumeration."

BAD: "User search endpoint" / "POST endpoint that searches users"

Headers — every header must have a description explaining PURPOSE:

GOOD: {"name": "Authorization", "value": "Bearer eyJ...", "required": true, "description": "JWT access token from POST /auth/login. RS256 signed, 1h expiry."}

BAD: {"name": "Authorization", "value": "Bearer token", "required": true, "description": "Auth header"} ← "Auth header" says nothing useful

OpenAPI Schema — every parameter must have a description:

GOOD: {"name": "user_id", "in": "path", "required": true, "description": "UUID of the target user. Found in GET /api/users response."}

BAD: {"name": "user_id", "in": "path", "required": true} ← no description

Example Calls — must be REAL requests with REAL responses:

  • Use curl -i to capture response headers
  • Include at least 1 example (ideally success + error case)
  • Never fabricate responses

When to Use This​

Trigger this skill whenever you encounter a new endpoint:

  • Network traffic during browsing or spidering
  • URLs found in JavaScript bundles or source maps
  • Paths revealed in error messages, stack traces, or redirects
  • Endpoints from OpenAPI/Swagger specs, GraphQL introspection, or WSDL
  • API paths found in mobile app reverse engineering
  • Links discovered in HTML source, comments, or sitemap.xml

If in doubt, delegate it. Registering a duplicate is harmless (the subagent checks), but missing an endpoint means it's invisible to the system.

How to Delegate​

Call the register-endpoint subagent via the Agent tool. Pass ALL context you have — the more you provide, the better the investigation.

REQUIRED in every delegation:

  1. HTTP method and full URL
  2. Service ID (look up with manage_services(action="list") if unknown)

INCLUDE if you have it: 3. Auth tokens/cookies/API keys (actual values, not placeholders) 4. How you discovered it 5. Parameters or headers you already observed 6. Status codes or responses you already saw

Examples​

Basic discovery during browsing:

Agent("register-endpoint", "Found POST /api/v2/users/search on service_id=5.
Discovered in network tab while browsing user management page.
Auth: Bearer eyJhbGciOiJSUzI1NiIs...
Saw it accepts JSON body with 'query' field.")

Endpoint found in JS bundle with detailed params:

Agent("register-endpoint", "Found POST /api/graphql on service_id=2.
Source: main.js bundle at https://app.target.com/static/main.js line 4521.
Saw queries: userSearch(query: String!, limit: Int), orderHistory(userId: ID!).
Also accepts X-Request-ID header (UUID).
Auth: Bearer eyJhbGciOiJIUzI1NiIs...")

Unauthenticated endpoint from error page:

Agent("register-endpoint", "Found GET /api/health/status on service_id=1.
Source: 500 error page leaked this path in a stack trace.
I already curled it unauthenticated and got 200 with JSON:
{\"status\":\"ok\",\"version\":\"2.3.1\",\"env\":\"production\"}.
No auth required. Server header: nginx/1.24.0.")

Endpoint from API documentation:

Agent("register-endpoint", "Found PUT /api/v1/users/{user_id}/settings on service_id=3.
Source: OpenAPI spec at https://api.target.com/docs/openapi.json.
Body: {notification_preferences: object, privacy_level: enum(public,private,friends)}.
Requires Bearer + Content-Type: application/json.
Token: Bearer eyJhbGci...")

Rules​

  • To register endpoints, always delegate to the register-endpoint subagent
  • NEVER skip registration because an endpoint seems unimportant — register everything
  • ALWAYS wait for the subagent to complete before continuing your work
  • If you discover multiple endpoints at once, register them one by one sequentially
  • If you don't have auth info, still delegate — unauthenticated probing is valuable