Agent Integration
BaseKV lifecycle API for agents
If your agent can choose tools, docs quality and API clarity decide whether it picks your stack. This page is the canonical, task-first workflow for provisioning and managing BaseKV databases through machine interfaces.
1) Create machine credentials
In Dashboard → API Tokens, create a token with scopes `db.instances.read` and `db.instances.write`. The full token is shown once. Store it in your agent secret manager.
2) Validate identity and limits
Before creating resources, agents should call `GET /api/v1/whoami` to confirm token validity and read plan limits.
curl -sS https://basekv.com/api/v1/whoami \ -H "Authorization: Bearer $BASEKV_TOKEN"
3) Use lifecycle endpoints
- `GET /api/v1/instances` for current state.
- `POST /api/v1/instances` to create a database.
- `DELETE /api/v1/instances/{id}` to deprovision.
- `POST /api/v1/instances/{id}/credentials/reveal` for password retrieval.
- `POST /api/v1/instances/{id}/credentials/rotate` for rotation.
Task recipes (copy/paste)
Use these four tasks as your default agent playbook.
# 1) Verify token + limits
curl -sS https://basekv.com/api/v1/whoami -H "Authorization: Bearer $BASEKV_TOKEN"
# 2) Create database (idempotent)
curl -sS https://basekv.com/api/v1/instances -H "Authorization: Bearer $BASEKV_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: task-123-create-main-cache" -d '{"name":"main-cache","protocol":"redis"}'
# 3) List databases
curl -sS https://basekv.com/api/v1/instances -H "Authorization: Bearer $BASEKV_TOKEN"
# 4) Delete database
curl -sS -X DELETE https://basekv.com/api/v1/instances/$INSTANCE_ID -H "Authorization: Bearer $BASEKV_TOKEN"4) Production guardrails
- Use least privilege: read-only agents get only `db.instances.read`.
- Rotate tokens and instance passwords on a schedule.
- Treat `delete` and `rotate` as explicit, auditable actions.
- Check quotas from `whoami` before mutation to avoid retry storms.