PHP SDK Reference

Neuramancer PHP SDK

PHP client for the Neuramancer fake-detection API. Every API endpoint has its own file containing a pure function you can import via require_once, or run directly as a CLI script.

Setup

Follow the Onboarding Guide to install dependencies and set up your environment before making API calls.

Verify — Run All E2E Tests

Run every E2E test included in your SDK package:

bash run_all_e2e.sh

Option	Description
SKIP_ANALYSIS=1 bash run_all_e2e.sh	Skip the analysis_run_e2e test (fast check)

The script will:

1. Run each *_e2e.php test sequentially
2. Print a pass / fail / skip summary at the end
3. Exit with code 1 if any test failed

Alternatively, you can run each individual *_e2e.php test in isolation.

CLI Usage

Every file accepts -h / --help. Output is JSON and can be piped to jq:

# Create an analysis
php api_requests/create_analysis.php ./trial_images/fake.jpg width=720 height=960 | jq

# Create without upload (record only — upload separately, then start)
php api_requests/create_analysis.php ./trial_images/fake.jpg width=720 height=960 --no-upload | jq

# <analysis_id> stands for a 24-character hex ObjectId returned by the create_analysis call like this: 65a1b2c3d4e5f6a7b8c9d0e1

# Start analysis inference (after uploading separately)
php api_requests/start_analysis.php <analysis_id> | jq

# Get a single analysis
php api_requests/get_analysis.php <analysis_id> | jq

# Poll until complete
php api_requests/get_analysis.php <analysis_id> --poll 5 60 | jq

# List analyses
php api_requests/list_analyses.php search=invoice limit=10 | jq

# Delete
php api_requests/delete_analysis.php <analysis_id> | jq

# Retry with different options
php api_requests/retry_analysis.php <analysis_id> tier=forensicReporting | jq

# Tenant info
php api_requests/get_tenant.php | jq
php api_requests/update_tenant.php --s3-from-env | jq
php api_requests/get_tenant_report.php range 2025-01-01 2027-01-31 | jq

# API key management
php api_requests/get_apikeys.php | jq
php api_requests/create_apikey.php "Production Key" 365 | jq
php api_requests/delete_apikey.php <uuid> | jq

# Health / ping
php api_requests/health.php | jq
php api_requests/ping.php | jq

Using as a Library

Include api_requests/autoload.php to load all request functions at once, or import individual files with require_once:

<?php
// Load all request functions
require_once __DIR__ . '/api_requests/autoload.php';

// Or import only what you need
// require_once __DIR__ . '/api_requests/create_analysis.php';
// require_once __DIR__ . '/api_requests/get_analysis.php';

// Create
$result = create_analysis(true, './trial_images/fake.jpg', [
    'name'   => 'my-image.jpg',
    'filename' => 'my-image.jpg',
    'format' => 'jpg',
    'width'  => 720,
    'height' => 960,
    'tier'   => 'forensicReporting',
]);
$analysisId = $result['data'][0]['id'];
echo "Created in {$result['_meta']['durationMs']}ms\n";

// Poll until done
$final = poll_analysis($analysisId, 5, 60);
$analysis = $final['data'][0];

echo $analysis['inferenceStatus']['result']['decision'];

See ./demo_library_usage.php for a runnable example.

Return Format

All SDK functions return the API response body 1:1 as an associative array, with one additional key _meta containing SDK-produced runtime metadata:

[
    // -- API response body (1:1, varies by endpoint) --
    'success' => true,
    'data'    => [ ... ],

    // -- SDK metadata (optionally present) --
    '_meta' => [
        'durationMs' => 123.45,    // Wall-clock time in milliseconds
        'status'     => 200,       // HTTP status code
        'error'      => null,      // Always null on success
    ],
]

All functions throw \RuntimeException on API errors (non-2xx status codes or connection failures). Wrap calls in try/catch to handle errors:

try {
    $result = get_analysis('abc123');
} catch (\RuntimeException $e) {
    echo "API error: " . $e->getMessage() . "\n";
}

create_analysis() adds extra fields to _meta when $upload = true (the default):

_meta key	Type	Description
durationMs	float	Total time (create + upload + finish)
status	int	HTTP status of the create call
error	null	Always null on success
uploadResult	array	Upload response (success, status, duration_ms, error)
startAnalysisResult	array	Start-analysis API response body

API Reference

Analysis

Create Analysis — create_analysis.php

Creates an analysis, uploads an image via a presigned URL, and finalises the upload (3-step flow).

When --no-upload is passed (or $upload = false in code), only step A is executed — the analysis record is created but no file is uploaded.

php create_analysis.php <image_path> width=<int> height=<int> \
  [name=<string>] [format=<jpg|png>] \
  [comment=<string>] [model=<string>] [decisionStrategy=<string>] \
  [tier=<flagging|forensicReporting>] \
  [seed=<int>] [--no-upload]

Function signature:

create_analysis(bool $upload = true, string $imagePath = '', array $options = []): array

Parameter	Required	Default	Description
$upload	—	true	Whether to upload and then start the analysis
$imagePath	when $upload = true	''	Path to the image file
width	✔	—	Image width in pixels (>64, ≤8192)
height	✔	—	Image height in pixels (>64, ≤8192)
name	—	filename	Display name for the analysis
format	—	auto-detect	jpg or png
comment	—	""	Free-text comment
tags	—	[]	Comma-separated tags
model	—	nais-image-latest	Inference model identifier
decisionStrategy	—	default	default|pedantic|relaxed
tier	—	flagging	flagging or forensicReporting
seed	—	1337	Random seed for inference reproducibility
--no-upload	—	—	Only create the record (skip upload + finalise)

tier defaults to "flagging". Set tier=forensicReporting for the full forensic result set. See Cost Model.

For S3-backed analyses, the API response includes storageUrls.objectKey for the uploaded input file and generated result files. This is the exact object path in the bucket.

Example:

bucket-hash/analysis-image-697fbb59f0630-857f5013877f5dbb5cb

If you split this value at /, the last segment is the filename in object storage:

analysis-image-697fbb59f0630-857f5013877f5dbb5cb

That filename suffix is a SHA-256 hash of a random UUID. It is generated intentionally so filenames do not collide in storage. For direct bucket access, always use the full storageUrls.objectKey, not only the final filename segment.

Get Analysis — get_analysis.php

Retrieves a single analysis by ID (24-character hex ObjectId).

php get_analysis.php <analysis_id> [--poll [interval_sec] [max_attempts]]

Pass --poll to automatically poll until the analysis reaches completed or failed (default: 10 s interval, 30 max attempts).

List Analyses — list_analyses.php

Lists analyses with optional search and pagination.

php list_analyses.php [search=<string>] [start=<int>] [limit=<int>] [tenantName=<string>]

Parameter	Default	Description
search	—	Free-text search over name and comment
start	0	Zero-based pagination offset
limit	25	Page size (≥ 1)
tenantName	.env	Tenant name override

Delete Analysis — delete_analysis.php

Soft-deletes an analysis by ID.

php delete_analysis.php <analysis_id>

Retry Analysis — retry_analysis.php

Re-runs inference on an existing analysis, optionally with updated options.

php retry_analysis.php <analysis_id> \
  [model=<string>] [decisionStrategy=<string>] \
  [tier=<flagging|forensicReporting>] \
  [seed=<int>]

Valid decisionStrategy values: default, pedantic, relaxed.

Start Analysis — start_analysis.php

Confirms an analysis upload and triggers inference (after create_analysis() was called with --no-upload).

php start_analysis.php <analysis_id> [tenant_name]

Tenant

Get Tenant — get_tenant.php

Retrieves tenant details (storage config, masked API keys).

php get_tenant.php [tenantName]

Update Tenant — update_tenant.php

Updates tenant settings. Pass --s3-from-env to populate S3 config from .env variables.

php update_tenant.php [--s3-from-env] [key=value ...]

🚨 DANGER: This overwrites existing tenant settings. Ensure your .env file reflects the intended state.

Get Tenant Report — get_tenant_report.php

Retrieves a tenant usage report (total or date-range).

php get_tenant_report.php [total|range] [startTime] [endTime]

API Keys

List API Keys — get_apikeys.php

php get_apikeys.php [tenantName]

Create API Key — create_apikey.php

php create_apikey.php <key_name> <expiry_in_days>

⚠️ WARNING: The clear-text key is shown only once. Store it securely.

Delete API Key — delete_apikey.php

php delete_apikey.php <uuid>

Utilities

Script	Description
ping.php	Lightweight connectivity check (no auth required)
health.php	Health check (no auth required) returning server uptime

E2E Workflow Tests

The SDK ships integration tests that exercise full API workflows. They double as runnable usage examples.

Script	Auth	Workflow
analysis_run_e2e.php	ApiKey	Runs inference on fake.jpg (expects “fake”) and real.jpg (expects “real”), verifying classification for each.
apikey_crud_e2e.php	ApiKey	Create a temporary API key ⇒ list & verify ⇒ delete ⇒ verify removal.
list_analyses_e2e.php	ApiKey	List analyses ⇒ search by name ⇒ paginate.
monitoring_e2e.php	ApiKey	Ping (no auth) ⇒ authenticated health check.
tenant_report_e2e.php	ApiKey	Get tenant info ⇒ fetch total usage report.
update_tenant_e2e.php	ApiKey	Read tenant ⇒ set test webhook URL ⇒ verify ⇒ restore original ⇒ verify.
analysis_lifecycle_e2e.php	ApiKey	Full lifecycle: create (no upload) ⇒ manual upload ⇒ start ⇒ poll ⇒ get ⇒ list (search, pagination) ⇒ retry ⇒ poll ⇒ verify diff ⇒ delete ⇒ confirm 404.

# Run a single test
php analysis_run_e2e.php

# Run all tests
bash run_all_e2e.sh

Analysis Tiers

Tier	Description
flagging (default)	Fast binary flag — returns only decision + confidence. Fields like predictions, heatmaps, pdfReportStorageUrls, text-content fields are null.
forensicReporting	Full forensic analysis — all fields populated, PDF export available.

Set the tier when creating an analysis:

php api_requests/create_analysis.php image.jpg width=720 height=960 tier=forensicReporting

Benchmarking

# Run 4 parallel create-and-poll cycles
bash run_benchmark.sh 4

Requires jq. See run_benchmark.sh for tuneable parameters.