Tenant Management

The Tenant API provides endpoints for retrieving tenant information and updating tenant settings. Each tenant represents an organization or account within the Neuramancer system.

Overview

Tenants are the top-level organizational unit in the Neuramancer API.

Each tenant has:

Unique identifier: Immutable unique id
Tenant name: Human-readable name (slug format)
Blob storage configuration: Azure or S3 settings - see Blob Storage Management
API keys: See API Key Management
Webhook configuration: Optional webhook URL for notifications - see Webhooks
Trial mode: System-managed flag restricting analyses to approved trial images only

Trial Mode

When a tenant has isTrial: true, the tenant is in trial mode. In this mode:

Only two approved trial images (real.jpg and fake.jpg) can be analyzed.
When POST /v1/analysis/start is called, the uploaded file’s MD5 checksum is validated against the approved trial images.
If the uploaded image does not match either trial image, the API returns HTTP 422 Unprocessable Entity.
The isTrial flag is read-only and cannot be changed via PUT /v1/tenant. It is managed by the system.

This ensures that trial tenants can only explore the platform with known reference images before upgrading to a full account.

Tenant Usage Reports

Retrieve a tenant usage report for a day, range, or cumulative total via GET /v1/tenant/report.

Query Parameters:

Parameter	Type	Required	Description
`tenantName`	string	Yes	Tenant name
`type`	enum	No	`total` - latest cumulative report; `range` - aggregated report for a date range. Defaults to `total` if omitted.
`startTime`	string (ISO 8601)	Conditional	Required when `type=range`. Start date. Defaults to current time if omitted.
`endTime`	string (ISO 8601)	Conditional	Required when `type=range`. End date. Defaults to current time if omitted.

Behaviour:

type=total => returns the all-time cumulative report with live queuedAnalyses.
type=range => aggregates daily reports in [startTime, endTime] and returns one aggregated report.
If startTime === endTime (single day), returns that day’s report directly.

Response (200 OK):

Both total and range types return a single report:

{
  "success": true,
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "tenantId": "507f1f77bcf86cd799439010",
    "updatedAt": "2026-02-17T12:30:45.123Z",
    "startTime": "2026-02-17T00:00:00.000Z",
    "endTime": "2026-02-17T23:59:59.999Z",
    "queuedAnalyses": 42,
    "successfulProcessing": {
      "byType": { "api": 150, "app": 85, "total": 235 },
      "byResult": {
        "fake": 48, "real": 165, "uncertain": 15, "abstain": 7,
        "total": 235, "confidenceScore": 0.91
      },
      "byModelTypeAndTier": {
        "image": { "forensicReporting": 80, "flagging": 155 }
      }
    },
    "userInteraction": { "appLogins": 12 },
    "impediments": { "processingErrors": 2, "retries": 3 },
    "qualityIndicators": { "errorRatePercent": 0.85, "backpressurePercent": 15.2 },
    "processingDurations": {
      "byModelTypeAndParallelism": {
        "image": { "single": 2.34, "bulk": null }
      }
    }
  }
}

TenantReport Fields

Field	Description
`tenantId`	Tenant identifier
`updatedAt`	Timestamp when the report was last updated
`startTime`, `endTime`	Exact start/end times for the reporting period
`queuedAnalyses`	Pending analyses at report generation time (live for today)
`successfulProcessing.byType`	Successful analyses by source: `api`, `app`, `total`
`successfulProcessing.byResult`	Breakdown by result class (`fake`, `real`, `uncertain`, `abstain`), plus `total` and `confidenceScore`
`successfulProcessing.byModelTypeAndTier`	Breakdown by model type (e.g. `image`) and tier (`forensicReporting`, `flagging`)
`userInteraction`	User interaction metrics (e.g., `appLogins`)
`impediments`	Error and retry counts (`processingErrors`, `retries`)
`qualityIndicators`	`errorRatePercent` and `backpressurePercent`
`processingDurations.byModelTypeAndParallelism`	Average durations grouped by model type (e.g. `image`) and parallelism mode (`single`, `bulk`), in minutes

Update Policy

Usage statistics are updated in real-time for daily reports and all-time totals. Range reports that belong to past days are updated daily by a scheduled job.

Usage Examples

Get the latest cumulative report:

GET /v1/tenant/report?tenantName=acme&type=total

Get today’s report:

GET /v1/tenant/report?tenantName=acme&type=range

Get a specific day’s report:

GET /v1/tenant/report?tenantName=acme&type=range&startTime=2026-02-17&endTime=2026-02-17

Get an aggregated week report:

GET /v1/tenant/report?tenantName=acme&type=range&startTime=2026-02-10&endTime=2026-02-17