Pingtower
Docs
Projects & sources
A project is a namespace inside a tenant. A source is one thing that sends into it, with its own token.
Projects
GET /v1/projects lists every project the tenant owns, name-ordered, each with name, config_version, sources, rules, open_alerts and created_at. Paginate with limit and after, passing the last name on the previous page.
POST /v1/projects with {"name": "…"} creates one. Projects are explicit rows: a typo in a path is a 404, never a project created by accident.
POST /v1/projects/{id}/rename and DELETE /v1/projects/{id} are owner or admin only, or any role with project_admin:write. Renaming does not break ingest tokens, which resolve through the source row. Deleting removes the project’s sources, rules, alerts and reports; a report’s public page stops resolving. Renaming moves the project’s incidents, browser-check history and invite grants with it, and a new project given an old or deleted name starts empty.
Sources
| Field | Meaning |
|---|---|
name | The source’s identity. Appears on every line and can be matched by rules. |
retain_logs | Keep raw lines for the log tail and log search. On when a new source leaves it out. Required explicitly on update. |
created_at |
POST /v1/projects/{id}/sources creates one and returns its pti_ ingest token. The token is shown once; there is no route that reads it back.
POST /v1/projects/{id}/sources/{name}/rotate-token mints a new token and invalidates the old one immediately, with no overlap window, so deploy the new token to the sender first and rotate second if a gap matters. Owner or admin only, or any role with project_admin:write.
DELETE /v1/projects/{id}/sources/{name} is owner or admin only, or any role with project_admin:write, and is refused with 409 while a rule’s match.sources still names it.
A project holds at most 200 sources; see Limits for the other per-project counts.
How to split things up
- One project per thing you would page separately. A service, an environment, a customer. Open-alert counts and the app’s project filter work at this level.
- One source per sender. Each app instance, host or probe gets its own token, so a leaked or retired one can be rotated without touching the rest, and rules can tell them apart.
- Tags for everything else. Region, tier, customer: put it in
tagson the line and match on it in the rule.
source_silent trigger that names the source: it opens an alert once the source has been quiet for longer than you set, and resolves on its own when lines arrive again. See Sources that go quiet.