# Projects & sources
Source: https://www.pingtower.com/docs/service/projects/
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. 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.
## 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](/docs/service/logtail/). Off by default. 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.
DELETE `/v1/projects/{id}/sources/{name}` is refused with `409` while a rule's `match.sources` still names it.
## 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 `tags` on the line and match on it in the rule.
Sources that go quietNothing in the service alerts on silence. A source that stops sending, including a dead addons agent, produces no lines and therefore no alert. If you need that, run a second agent and use distinct_sources, or watch the agent’s heartbeat from something else.