> For the complete documentation index, see [llms.txt](https://vampauth.gitbook.io/vampauth-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vampauth.gitbook.io/vampauth-docs/api-reference/loader-protocol.md).

# Loader protocol

The dashboard bootstrap already implements this protocol. Use the normal snippet unless you are debugging an integration.

## GET /v1/loaders/{hash}.lua

Downloads the bootstrap as text/plain. The hash is 32 lowercase hex characters. The route also accepts the clean hash form. Downloads don't invoke publishing or consume publishing credits.

Limit: 60 requests/minute/IP. Success can be cached for 60 seconds; errors use no-store. A missing loader returns 404; throttling returns 429 with Retry-After: 60.

## POST /v1/loaders/{hash}

JSON fields: `key`, `hwid`, optional `instance`, `fingerprint`, capability telemetry and fingerprint signals. The body reader allows up to 8 KiB. A provided HWID/fingerprint uses a 64-character lowercase SHA-256 digest; session instance identifiers follow the bootstrap's format.

The server resolves the URL's project, checks its current policy and key, chooses the payload, and admits the run. Keyed success returns a signed temporary `link`, `size`, session/runtime metadata, and expiry information used by the bootstrap. The link lasts about 60 seconds. Keyless success delivers payload bytes directly with an X-Vampauth-Size header instead of the keyed link flow.

Limit: 30 requests/minute/IP. Validation failures return an error code and often a human-readable message. Common statuses: 400 invalid\_request, 404 invalid\_key/loader\_not\_found, 403 key\_revoked/blacklisted/hwid\_mismatch, 410 key\_expired, and 409 instance\_limit/configuration\_changed.

## POST /v1/loaders/{hash}/beat

Body fields: `session`, `instance`, optional `hwid`, `executor`, `lease_enabled`, and `release`. The token is bound to its loader/device/instance scope. A client flag cannot downgrade a durable lease.

Success is HTTP 200 with `ok: true` and lease metadata where applicable. `release: true` asks to release the session. Expired/missing sessions return 404 with `session_expired` or `session_not_found`; malformed input returns 400. Limit: five requests/minute/session, with additional IP protection for durable-lease lookups.

Advisory heartbeats track process-local presence. Durable lease renewal performs server authorization. Don't treat a successful advisory heartbeat as proof that a key is still valid.

## Retired routes

Old /client/vampauth.lua, /client/vampauth-core.lua, /api/v1/key/activate, and project raw/loadstring delivery are retired. See the reference-client migration guide.

## Next steps

* [Loader](/vampauth-docs/development/loader.md)
* [Loader errors](/vampauth-docs/troubleshooting/loader-errors.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://vampauth.gitbook.io/vampauth-docs/api-reference/loader-protocol.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.