# GraphQL versioning

> How Done Bear evolves the GraphQL schema, marks retiring fields with @deprecated, and sunsets documented fields.

Done Bear does not version the GraphQL URL. There is one schema at `https://api.donebear.com/graphql`. Breaking changes are announced, then marked, then removed.

## Stability

Fields and operations documented on [GraphQL reference](/api/graphql) are stable. Undocumented schema details may change without notice.

## Deprecation

When a field is retiring, it stays in the schema with GraphQL `@deprecated` and a reason that names the replacement.

Example: `Task.notes` is deprecated. Use `Task.description`. The CLI flag remains `--notes`.

Introspect deprecations with:

```graphql
{
  __type(name: "Task") {
    fields(includeDeprecated: true) {
      name
      isDeprecated
      deprecationReason
    }
  }
}
```

## Sunset

A deprecated field remains queryable for at least 90 days after the deprecation reason lands in the schema. After that window it may be removed. Removals of previously documented query fields are listed in the API changelog and guarded by the schema test that tracks retired names.

## Rate limits and cost

The `Query` and `Mutation` types carry a `@rateLimit(limit: 100, durationSeconds: 60)` directive. That matches the API origin's per-IP ceiling (100 requests per 60 seconds). Query depth is capped at 10. The hosted MCP server has a separate per-token limit of 120 requests per minute.

There is no per-field query-cost budget beyond that depth cap.

## Next steps

- [GraphQL reference](/api/graphql)
- [API scopes](/api/scopes)
- [OpenAPI specification](https://donebear.com/openapi.json)