openapi: 3.1.0
info:
  title: Nasak Platform Administration API
  version: 1.0.0-alpha.1
  description: Central stores, users, entitlements, monitoring, logs, analytics, settings, and API documentation.
servers:
  - url: https://api.nasak.ir/v1/platform/admin
paths:
  /stores:
    get:
      operationId: listPlatformStores
      summary: List and filter stores with platform health and usage
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
    post:
      operationId: createPlatformStore
      summary: Create a store and initial owner context
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited compatibility mutation.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /stores/{id}:
    patch:
      operationId: updatePlatformStore
      summary: Update store lifecycle state without permanent deletion
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited archive or status mutation.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
  /stores/{id}/overview:
    get:
      operationId: getPlatformStoreOverview
      summary: Get store ownership, usage, domain, service health, and recent audit data
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
  /stores/{id}/entitlements:
    get:
      operationId: getPlatformStoreEntitlements
      summary: Get allowed features, providers, limits, and usage
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
    patch:
      operationId: updatePlatformStoreEntitlements
      summary: Grant or revoke store features and limits
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited compatibility mutation with server-side enforcement.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
  /stores/{id}/managers:
    get:
      operationId: listPlatformStoreManagers
      summary: List store managers and effective permissions
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
    post:
      operationId: addPlatformStoreManager
      summary: Add a store manager with explicit permissions
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited compatibility mutation.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '201': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /stores/{id}/managers/{userId}:
    patch:
      operationId: updatePlatformStoreManager
      summary: Update a manager role and exact permission matrix
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/UserId' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited compatibility mutation.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
    delete:
      operationId: removePlatformStoreManager
      summary: Revoke a manager membership
      parameters: [{ $ref: '#/components/parameters/Id' }, { $ref: '#/components/parameters/UserId' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited membership revocation.
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
  /users/{id}:
    get:
      operationId: getPlatformUser
      summary: Get a safe administrative user profile
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
    patch:
      operationId: updatePlatformUser
      summary: Update user status and administrative fields
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited compatibility mutation.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
    delete:
      operationId: archivePlatformUser
      summary: Archive a user without destructive data removal
      parameters: [{ $ref: '#/components/parameters/Id' }]
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Audited archive operation.
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' }, '404': { $ref: '#/components/responses/NotFound' } }
  /system/health:
    get:
      operationId: getPlatformSystemHealth
      summary: Get safe provider, token, worker, database, and service health
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /system/resources:
    get:
      operationId: getPlatformSystemResources
      summary: Get safe CPU, memory, disk, and process resource metrics
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /logs:
    get:
      operationId: listPlatformLogs
      summary: Search redacted platform, user interaction, audit, and service logs
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /analytics:
    get:
      operationId: getPlatformAnalytics
      summary: Get aggregate interaction and traffic analytics
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /api-docs:
    get:
      operationId: getPlatformApiInventory
      summary: Get API migration status and route inventory
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /api-docs/openapi:
    get:
      operationId: getPlatformOpenApiDocument
      summary: Get an approved OpenAPI document for collaborators
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /settings/{key}:
    patch:
      operationId: updatePlatformSetting
      summary: Update an allowlisted non-secret platform setting
      parameters:
        - name: key
          in: path
          required: true
          schema: { type: string, minLength: 1, maxLength: 120 }
      security: [{ cookieSession: [] }]
      x-idempotency-exempt: true
      x-migration-note: Secret values are never accepted or returned by this compatibility API.
      requestBody: { $ref: '#/components/requestBodies/Mutation' }
      responses: { '200': { $ref: '#/components/responses/Success' }, '400': { $ref: '#/components/responses/BadRequest' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
  /management:
    get:
      operationId: getPlatformManagementDashboard
      summary: Get the central management dashboard aggregate
      security: [{ cookieSession: [] }]
      responses: { '200': { $ref: '#/components/responses/Success' }, '401': { $ref: '#/components/responses/Unauthorized' }, '403': { $ref: '#/components/responses/Forbidden' } }
components:
  securitySchemes:
    cookieSession: { type: apiKey, in: cookie, name: pdf_library_session }
  parameters:
    Id: { name: id, in: path, required: true, schema: { type: string, format: uuid } }
    UserId: { name: userId, in: path, required: true, schema: { type: string, format: uuid } }
  requestBodies:
    Mutation:
      required: true
      content:
        application/json:
          schema: { type: object, additionalProperties: true }
  schemas:
    Error: { type: object, additionalProperties: true, required: [error], properties: { error: { type: string } } }
  responses:
    Success: { description: Successful admin-scoped response, content: { application/json: { schema: { type: object, additionalProperties: true } } } }
    BadRequest: { description: Invalid request, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    Unauthorized: { description: Authentication is required, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    Forbidden: { description: Platform administrator access is required, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }
    NotFound: { description: Resource not found, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }