# DevSnorte Community — LLM usage guide > This document teaches automated agents (LLMs, scripts, integrations) > how to interact with the DevSnorte community platform on behalf of a > real human user. Every request is attributed to the user whose API key > is presented — treat those keys as personal credentials. ## Authentication All endpoints require an HTTP `Authorization: Bearer ` header. Tokens are personal API keys generated by the user in the dashboard at `/users/api-keys`. Tokens start with `dsn_`. They expire (up to 90 days) and can be revoked at any time by the user. There is **no agentic sign-in flow yet**. Do not try to log a user in through the browser session; the user must generate a token in the UI and paste it into the agent's configuration. Two scopes exist: - `read` — can call any `GET` endpoint. - `read_write` — additionally can `POST`, `PUT`, `PATCH`, `DELETE`. The API rate-limits requests per key (60/minute by default) and the whole host is protected against DDoS at 300 req/min per IP. Respect `Retry-After` on `429` responses. ## Base URL and content types - Base URL: same origin as the site (see `/api/openapi.json` for the exact host). - Requests and responses use JSON. Always send `Content-Type: application/json` on write requests. ## Discovery - OpenAPI 3.1 spec: `GET /api/openapi.json` - Swagger UI: `GET /api/docs` - Human-readable docs (how to generate a token, curl examples, rate limits): `GET /desenvolvedores` ## Public, read-only endpoints (no token required) These mirror what the site itself shows publicly — no `Authorization` header needed. They're rate-limited by IP (the same 300 req/min global limit) and cache-friendly (`Cache-Control: public, max-age=60`). ### `GET /api/v1/eventos` Upcoming approved eventos (projects in the "eventos" category), soonest first. Query params: `limit` (default 6, max 50), `days` (restrict to eventos starting within N days). ### `GET /api/v1/projetos` Approved projects. Query params: `q` (free-text search), `categoria` (category slug), `tag`, `page`, `per_page` (max 100). ### `GET /api/v1/projetos/:slug` A single approved project, with `categories`, `tags` and `contributors`. `:slug` is the trailing segment of `canonical_url` (e.g. `minha-api-42`, from the item's `slug` field) — the bare numeric id also works. Both `/eventos` and `/projetos` items share the same shape: `id`, `title`, `slug`, `short_description`, `full_description`, `main_image_path`, `url`, `event_*`, `cfp_*`, `canonical_url`, `author` (`username`, `avatar_url`), `categories`, `tags`, `inserted_at`, `updated_at`. `/projetos/:slug` adds `contributors` (`name`, `email`, `url`). ### `GET /api/v1/categorias` All categories with `id`, `name`, `slug`, `icon`, `color`, `project_count`, `canonical_url`. ## Authenticated endpoints ### `GET /api/v1/me` Validates the bearer token and returns the owning user (`id`, `username`, `role`) plus the key's `scope` (`read` or `read_write`). Use this to confirm a token works and discover what it can do before calling anything else — e.g. what `devsnorte login` does. ### `GET /api/v1/projects` Lists approved projects. Supports the same filters as the public UI: - `search` — free-text search over title and short description - `category_id` / `category_slug` — filter to a category - `tag` — exact tag match - `sort=votes` — sort by upvotes desc (default is newest) - `page`, `per_page` (max 100) - `mine=true` — returns the caller's own projects, including drafts and pending-review projects (which are otherwise not visible in the API). ### `GET /api/v1/projects/:id` Returns a single approved project, OR one of the caller's own projects in any status. ### `POST /api/v1/projects` Creates a project for the calling user. Requires `read_write` scope. Body: ```json { "project": { "title": "…", "short_description": "…", "full_description": "…", "url": "https://…", "category_ids": [1], "tags_string": "elixir, phoenix" } } ``` The project is created with `status: "draft"` — `status` itself is not a writable field (attempting to set it in the body has no effect). To send it to moderation, call `POST /api/v1/projects/:id/submit` separately (see below). The `user_id` is always set to the caller. Attempting to set it in the body has no effect. If you're a CLI integration (as opposed to a generic script), send `X-Devsnorte-Client: cli` so the origin is recorded correctly — it otherwise defaults to `"api"`. Either way the project's `source` field and the moderation queue will show it didn't come from the web form. ### `PUT /api/v1/projects/:id` (or `PATCH`) Updates a project the caller owns. 404 if the project is not owned by the caller. Same body shape as `POST`. ### `POST /api/v1/projects/:id/submit` Submits a project you own for review: moves it from `draft`/`rejected` to `pending_review` (or straight to `approved` if you're a trusted user). 422 if the project isn't a draft or rejected. This endpoint also has its own rate limit — 10 submissions per user per day, independent of the per-key, per-minute limit — so respect `Retry-After` on `429` here too. ### `DELETE /api/v1/projects/:id` Deletes a project the caller owns. Returns 204. ## Datetime handling All datetime fields in the API are **UTC**, serialized as ISO 8601 with a `Z` suffix (e.g. `"2024-01-15T10:30:00Z"`). When sending `event_start_date` or `event_end_date`, you **must** include an explicit timezone offset. Naive strings like `"2024-01-15T10:30:00"` are rejected with a 422. Any offset is accepted and converted to UTC server-side. Date-only fields (`cfp_start_date`, `cfp_end_date`) use the `YYYY-MM-DD` format and carry no timezone. ## Error responses All errors are JSON: ```json {"error": {"code": "invalid_token", "message": "…"}} ``` Validation errors from write endpoints are: ```json {"errors": {"title": ["can't be blank"], "…": ["…"]}} ``` ## Agent etiquette - Announce yourself with a descriptive `User-Agent` header including your agent name and the human operator's contact. - Never share a user's API key with third parties. - On `401`, stop and ask the user for a new key; do not retry automatically. - On `429`, back off using `Retry-After`. - Prefer to leave a project as a draft and let the user review it before calling `POST /api/v1/projects/:id/submit` to send it to moderation.