fix: add scopes field to API key schemas in OpenAPI docs

[WiZzArD07]

What I changed

• Added scopes field to ApiKey, ApiKeyCreated, and CreateApiKey schemas

Why

The implementation supports API key scopes, but this field was missing from the OpenAPI documentation.

Related Issue

Fixes #6698

[greptile-apps]

Greptile Summary

This PR adds the missing scopes field to ApiKey, ApiKeyCreated, and CreateApiKey schemas in the OpenAPI spec. The implementation is accurate: response schemas (ApiKey/ApiKeyCreated) correctly use type: ["array", "null"] to reflect that legacy keys return null, the request schema (CreateApiKey) exposes the correct enum of 8 available scopes, and the default read-only scope list in the description matches READ_ONLY_SCOPES in the backend exactly.

Confidence Score: 5/5

Safe to merge — documentation-only change with no runtime impact.

The three schema additions are accurate against the backend models and database layer. Nullable types match the Optional[List[str]] Pydantic fields and the legacy-key null-assignment in get_dev_keys_for_user. The enum values match AVAILABLE_SCOPES and the default description matches READ_ONLY_SCOPES. No P0 or P1 issues found.

No files require special attention.

Important Files Changed

Filename	Overview
docs/api-reference/openapi.json	Adds scopes field to ApiKey, ApiKeyCreated, and CreateApiKey schemas; nullable types and enum values are accurate and consistent with the backend implementation.

Sequence Diagram

sequenceDiagram
    participant Client
    participant API as POST /v1/dev/keys
    participant DB as Firestore

    Client->>API: CreateApiKey { name, scopes? }
    Note over API: if scopes is None → READ_ONLY_SCOPES
    API->>DB: store key + scopes
    DB-->>API: key doc
    API-->>Client: ApiKeyCreated { id, name, key, scopes }

    Client->>API: GET /v1/dev/keys
    API->>DB: query by user_id
    DB-->>API: key docs (scopes may be null for legacy keys)
    API-->>Client: List[ApiKey] { id, name, scopes (null|array) }

Loading

_{Reviews (2): Last reviewed commit: "fix: address review - make scopes nullab..." | Re-trigger Greptile}

[greptile-apps]

scopes should be marked nullable in response schemas

DevApiKey.scopes is typed Optional[List[str]] = None in the backend model, and get_dev_keys_for_user explicitly sets it to None for backward-compatible keys that predate the scopes feature. The GET endpoint can therefore return "scopes": null for existing keys. The current schema (type: "array") implies the field is always an array, which will mislead consumers who rely on the spec. To match last_used_at's pattern, both ApiKey.scopes and ApiKeyCreated.scopes should use type: ["array", "null"].

Suggested change

	"scopes": {
	"type": "array",
	"items": { "type": "string" },
	"description": "Permission scopes assigned to the API key."
	}
	"scopes": {
	"type": ["array", "null"],
	"items": { "type": "string" },
	"description": "Permission scopes assigned to the API key. Null for legacy keys (treated as read-only)."
	}

[greptile-apps]

ApiKeyCreated.scopes also needs nullable type

Same issue as ApiKey.scopes — DevApiKeyCreated extends DevApiKey and inherits scopes: Optional[List[str]] = None. Old keys retrieved after creation can still surface a null value here.

Suggested change

	"scopes": {
	"type": "array",
	"items": { "type": "string" },
	"description": "Permission scopes assigned to the API key."
	}
	"scopes": {
	"type": ["array", "null"],
	"items": { "type": "string" },
	"description": "Permission scopes assigned to the API key. Null for legacy keys (treated as read-only)."
	}

[greptile-apps]

Inconsistent indentation and missing valid scope values

The scopes block in ApiKeyCreated and CreateApiKey has an extra leading space (11 spaces vs 10 for all other properties) that is inconsistent with the rest of the file. This is purely cosmetic but worth fixing for consistency.

Additionally, the description "Optional scopes to assign. Defaults to read-only if not provided." doesn't mention what valid values look like. The developer.py router docstring lists all 8 available scopes (conversations:read/write, memories:read/write, action_items:read/write, goals:read/write). Adding an enum or at least listing them in the description would make this self-contained.

Suggested change

	"scopes": {
	"type": "array",
	"items": { "type": "string" },
	"description": "Optional scopes to assign. Defaults to read-only if not provided."
	}
	"scopes": {
	"type": "array",
	"items": {
	"type": "string",
	"enum": [
	"conversations:read", "conversations:write",
	"memories:read", "memories:write",
	"action_items:read", "action_items:write",
	"goals:read", "goals:write"
	]
	},
	"description": "Optional scopes to assign. Defaults to read-only (conversations:read, memories:read, action_items:read, goals:read) if not provided."
	}

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[WiZzArD07]

Updated the schemas to address review comments. Let me know if anything else needs adjustment .

[WiZzArD07]

Hi! I've addressed the review feedback and updated the schemas (nullable scopes, enum, formatting).

Would appreciate a review when you have time.

[github-actions]

Hey @WiZzArD07 👋

Thank you so much for taking the time to contribute to Omi! We truly appreciate you putting in the effort to submit this pull request.

After careful review, we've decided not to merge this particular PR. Please don't take this personally — we genuinely try to merge as many contributions as possible, but sometimes we have to make tough calls based on:

• Project standards — Ensuring consistency across the codebase
• User needs — Making sure changes align with what our users need
• Code best practices — Maintaining code quality and maintainability
• Project direction — Keeping aligned with our roadmap and vision

Your contribution is still valuable to us, and we'd love to see you contribute again in the future! If you'd like feedback on how to improve this PR or want to discuss alternative approaches, please don't hesitate to reach out.

Thank you for being part of the Omi community! 💜

[WiZzArD07]

@beastoin
Thanks for the review and for considering my contribution!

I understand the decision. I really enjoyed working on this and would love to contribute again.

If there are any areas where contributions are currently more helpful, I’d be happy to work on those 🙂