API

Draft service boundary

This API page separates the future public AI answer API from the protected account and admin API scaffold for credits, usage logs, and API keys.

Availability

Public AI APINot available

OpenAPI draftPublished as static JSON

Account APIScaffolded

Admin APIScaffolded

Google loginNeeds Cognito deploy

Draft Endpoints

POST /v1/ask

Ask a product question with optional page, locale, session, and previous-context data.

GET /v1/products/{id}

Read a normalized product summary, known aliases, variants, and source references.

POST /v1/sessions

Create a conversation session for web, retail, or partner client use.

POST /v1/products/search

Search normalized product identities, aliases, model numbers, and known source traces.

GET /v1/me

Read the signed-in user's profile, credit balance, active API keys, and recent usage records.

POST /v1/api-keys

Create a server-side API key. The plaintext secret is returned once and only a hash is stored.

GET /v1/admin/members

Admin-only member operations surface for credits, token limits, API keys, usage logs, and audit records.

Static draft: /openapi/speconaut.v0.json

Account API Model

Speconaut is expected to use Google login through Cognito Hosted UI, then call protected account and admin APIs with a Cognito JWT. Admin routes require the SpeconautAdmins Cognito group.

Contract Notes

{
    "question": "Which phone is better for camera work?",
    "locale": "en-US",
    "context": {
      "source": "specifications.global",
      "previous": "optional follow-up context"
    },
    "answer_format": "markdown"
  }