BaseCite Portal API

openapi: 3.2.0
info:
  title: BaseCite Stable AI Context Portal API
  version: v1-phase28
  summary: Bounded API for customer-submitted/unverified AI-readable context.
  description: 'This API exposes controlled, bounded AI context only. Developer discovery: https://basecite.com/docs and Smithery MCP registry listing: https://smithery.ai/servers/alwaysrememberme1024/basecite. It does not verify truth, companies, sources, legal authority, rankings, certification, endorsements, or AI/search adoption.'
servers:
- url: https://api.basecite.com
tags:
- name: Portal
paths:
  /portal/config:
    get:
      summary: Return customer and delegated upload route/config metadata
      parameters:
      - name: surface
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - customer
          - solution_company
          default: all
      responses:
        '200':
          description: Portal config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getPortalConfigResponse'
      operationId: getPortalConfig
      tags:
      - Portal
components:
  schemas:
    getPortalConfigResponse:
      allOf:
      - $ref: '#/components/schemas/ApiResponse'
      - type: object
        properties:
          data:
            type: object
            properties:
              entry:
                type: string
                format: uri
              account_required:
                type: boolean
              email_verification_required:
                type: boolean
              customer_authorized_uploaders_only:
                type: boolean
            additionalProperties: true
    ApiResponse:
      type: object
      additionalProperties: true
      properties:
        request_id:
          type: string
        trace_id:
          type: string
        data:
          type: object
          additionalProperties: true
  securitySchemes:
    aiReaderApiKey:
      type: apiKey
      in: header
      name: x-api-key
    sandboxApiKey:
      type: apiKey
      in: header
      name: x-api-key
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.basecite.com/oauth/token
          scopes:
            customer_upload: Create and complete organization-scoped customer uploads.
            metadata_read: Read metadata and canonical upload status for the bound organization.
            ai_readiness: Read bounded AI-readiness and processing metadata for the bound organization.
            ai_context: Read bounded AI context for the bound organization.
            mcp: Use authenticated bounded MCP tools for the bound organization.
            correction: Create organization-scoped upload corrections.
            origin_cairn_reference: Attach organization-scoped OriginCairn references.
x-basecite-sandbox:
  url: https://api.basecite.com/sandbox
  api_info: https://api.basecite.com/api/v1/sandbox
  key_issuance: https://api.basecite.com/api/v1/sandbox/keys
  free: true
  production_data_access: false
  persistence: false
x-basecite-boundary: customer_submitted_unverified_private_beta
x-basecite-public-downloadable: false
x-basecite-unbounded-export: false
x-basecite-batch-bulk:
  available: false
  reason: BaseCite intentionally exposes one organization and one upload per operation; no batch or bulk endpoint is advertised in v1.
x-basecite-api-lifecycle:
  policy_url: https://basecite.com/docs/developers#versioning-and-deprecation
  versioning: URL versioning under /api/v1/
  deprecation_notice: Retiring operations advertise Deprecation and Sunset response headers at least 90 days before removal.
  compatibility: Existing v1 operations remain backward-compatible during the published support window.
x-basecite-truth-verification-claim: false
x-basecite-phase32-solution-company-upload: true
x-basecite-phase33-self-documenting-status-sync: true
x-basecite-phase34-portal-ux: true
x-basecite-phase35-private-object-storage-boundary: true
x-basecite-phase36-ai-mcp-anti-scraping-access-policy: true
x-basecite-phase37-tenant-scoped-credentials: true
x-basecite-deprecation-policy: Breaking changes require a new /api/vN path. Deprecated fields remain documented for one version and emit Deprecation and Sunset headers before removal.
x-basecite-async-job-pattern: Long-running processing is represented by upload status polling and immutable sequence transitions; clients must not infer completion from elapsed time.
x-basecite-rate-limit:
  headers:
  - RateLimit-Limit
  - RateLimit-Remaining
  - RateLimit-Reset
  - Retry-After
  response: 429
x-basecite-pagination: List-like responses use explicit limit and cursor metadata when available; clients must not infer completeness from a truncated page.