Summary

An automated documentation audit noticed several places where the documented behavior may not match the current implementation, especially around the developer API auth/authorization model and a few operational runbooks. Some of these may be intentional or may reflect context the tool could not infer, but they seemed worth flagging for review.

Note: This issue was generated automatically by LyingDocs, a documentation-code misalignment detection tool. The analysis may contain errors or misinterpretations — please feel free to close or correct this issue if any finding does not apply or if we have misunderstood the codebase.

Finding Categories

The findings below are classified into one or more of the following categories:

Findings

Developer API key management auth appears different from the OpenAPI security model

• Category: LogicMismatch
• Documentation reference: docs/api-reference/openapi.json:22-25,809-814
• Code reference: backend/routers/developer.py:61

The OpenAPI spec appears to apply a global developer bearer/API-key auth scheme to the developer API, but it looks like /v1/dev/keys endpoints use Firebase user bearer tokens via get_current_user_id, while /v1/dev/user/... routes use developer API keys with the omi_dev_ prefix. If that reading is correct, clients following the spec may authenticate /v1/dev/keys incorrectly.

API key revoke endpoint may not return the documented 404 for missing keys

• Category: LogicMismatch
• Documentation reference: docs/api-reference/openapi.json:783-804
• Code reference: backend/database/dev_api_key.py:72

The spec documents DELETE /v1/dev/keys/{key_id} as returning 404 when the key is not found. In the implementation, it appears the delete path may silently no-op unless the key exists and belongs to the user, with the route still returning 204. If so, missing keys would be reported as successfully deleted rather than not found.

Developer API scopes and 403 authorization behavior appear undocumented

• Category: ShadowLogic
• Documentation reference: docs/api-reference/openapi.json:22-25,34-806
• Code reference: backend/dependencies.py:79

It appears that developer API keys carry scopes, newly created keys default to read-only scopes, and write endpoints for memories, conversations, and action items can reject otherwise valid keys with 403 for insufficient permissions. We could not find scope behavior, default read-only behavior, or these 403 responses documented in the OpenAPI spec.

API key schemas may be missing the implemented scopes field

• Category: ShadowLogic
• Documentation reference: docs/api-reference/openapi.json:717-780,1035-1061
• Code reference: backend/models/dev_api_key.py:7

Related to the previous item, the create/list API key flows appear to support a scopes field in requests and responses, and omitted scopes seem to default to READ_ONLY_SCOPES. The documented schemas for CreateApiKey, ApiKey, and ApiKeyCreated appear not to include this field, which may make permission assignment unclear for API consumers.

Paid-plan lock filtering and 402 responses may be missing from the developer API docs

• Category: ShadowLogic
• Documentation reference: docs/api-reference/openapi.json:34-806
• Code reference: backend/routers/developer.py:173

The developer data endpoints appear to apply paid-plan gating through is_locked checks. From the code, it seems some list endpoints filter out locked resources, while some item operations can return HTTP 402 for locked memories, conversations, or action items. We did not see this monetization/availability behavior documented in the API spec.

Developer conversation creation may not run app integrations as described

• Category: LogicMismatch
• Documentation reference: docs/api-reference/openapi.json:315-318
• Code reference: backend/routers/developer.py:789

The OpenAPI description for creating a conversation from text says the request runs the full AI pipeline including app integration and webhooks. However, it appears the developer route calls process_conversation but does not call trigger_external_integrations, while the non-developer route does. If that is intentional, the current description may overstate what the developer endpoint does.

Simulator flavor-to-host mapping may be less deterministic than the runbook says

• Category: LogicMismatch
• Documentation reference: docs/runbooks/simulator.md:3-7
• Code reference: app/lib/env/prod_env.dart:7

The simulator runbook states that flutter run --flavor dev uses api.omiapi.com and --flavor prod uses api.omi.me. From the code, it seems the flavor selects DevEnv vs ProdEnv, but the actual backend URL comes from env files (.dev.env for dev and .env for prod). If so, the host mapping is not guaranteed by the flavor flag alone.

Flutter log path may be an operator convention rather than a fixed application path

• Category: HardcodedDrift
• Documentation reference: docs/runbooks/logging.md:3-7; runbooks/simulator.md:25-28
• Code reference: app/e2e/SKILL.md:25

The runbooks present /tmp/flutter-run.log as the log location, but it looks like logging is just stdout redirection and the repository uses multiple filenames, including /tmp/omi-flutter.log. If so, the documented path may be better described as an example command convention rather than a fixed application log sink.

backend-listen logging instructions may point to the wrong platform

• Category: LogicMismatch
• Documentation reference: docs/runbooks/logging.md:9-12
• Code reference: backend/charts/backend-listen/Chart.yaml:1

The logging runbook suggests querying Cloud Run logs for service backend-listen, but the repository appears to define backend-listen as a Helm/Kubernetes deployment, and the deployment workflows seem to send *-listen services to GKE rather than Cloud Run. If that is correct, the runbook may be pointing operators to the wrong log source.

agent-proxy log command may use a pod label selector that is not present in the chart

• Category: LogicMismatch
• Documentation reference: docs/runbooks/logging.md:14-17
• Code reference: backend/charts/agent-proxy/templates/_helpers.tpl:46

The runbook says agent-proxy logs can be fetched with kubectl logs -n prod-omi-backend -l app=agent-proxy, but the chart appears to label pods with app.kubernetes.io/name and app.kubernetes.io/instance instead of app=agent-proxy. If we read that correctly, the documented selector may not match deployed manifests.

Documentation index appears to reference missing .cursor markdown files

• Category: PhantomSpec
• Documentation reference: docs/INDEX.md:78-80
• Code reference: .cursor/hooks.json:1

The documentation index links to .cursor/ARCHITECTURE.md, .cursor/API_REFERENCE.md, and .cursor/DATA_FLOW.md, but those files do not appear to be present in the repository snapshot analyzed by the tool. This may leave users with dead links unless those files are generated elsewhere or intentionally omitted.

Desktop auto-release workflow may do more than the deploy runbook describes

• Category: ShadowLogic
• Documentation reference: docs/runbooks/deploy.md:25-28
• Code reference: .github/workflows/desktop_auto_release.yml:24

The deploy runbook describes the desktop auto-release workflow as a version bump plus tag creation before Codemagic builds. However, the workflow also appears to deploy the desktop backend to development and then production before creating the release tag. If that is expected behavior, it may be helpful to document it because it affects release sequencing and operational expectations.

Suggested follow-up

• Review whether the OpenAPI spec should distinguish Firebase-authenticated key-management endpoints from developer-key-authenticated data endpoints.
• Document the developer API authorization model more explicitly, including scopes, default read-only behavior, possible 403 responses, and any 402 paid-plan gating behavior.
• Reconcile endpoint response docs with implementation for cases like API key deletion and developer conversation creation, or clarify if the code is the part that should change.
• Update runbooks and index links where needed so operational commands, deployment descriptions, and referenced files match the current repository layout and infrastructure.

If any of the above findings are false positives or we have misunderstood the context, we sincerely apologize for the noise. Please close this issue or leave a comment and we will take note.