API Reference

The Photoniq REST API accepts UCDB uploads and RTL index submissions and returns ranked test vector recommendations as JSON. All requests require Bearer token authentication.

Authentication

Pass your API key in the Authorization header:

Authorization: Bearer phnq_live_<your_api_key>

Obtain your key from your account dashboard. Keys are scoped per project and per tier. Rotate keys at any time without downtime.

Base URL

https://api.photoniqo.com/v1

Error codes

All errors return JSON with error.code and error.message:

{
  "error": {
    "code": "UCDB_PARSE_FAILED",
    "message": "Could not parse UCDB file: unexpected EOF at bin record 4821",
    "request_id": "req_9Hx7k2mVpT"
  }
}

POST /analyze

Submit a coverage database + RTL index for analysis. Returns a job_id you poll with GET /results.

Request

Multipart form or JSON body:

Content-Type: multipart/form-data

ucdb_file: <binary UCDB file>
rtl_index: <JSON string — output of `phnq index ./src/rtl`>
project_id: proj_4xMv9kLpQr (optional — uses default project if omitted)
options: {"max_recommendations": 10, "min_confidence": 0.6}

Response — 202 Accepted

{
  "job_id": "job_8Pm3nKqRsT",
  "status": "queued",
  "project_id": "proj_4xMv9kLpQr",
  "estimated_seconds": 5,
  "poll_url": "https://api.photoniqo.com/v1/results/job_8Pm3nKqRsT"
}

GET /results/{job_id}

Poll analysis status. Returns status: "processing" until complete, then the full manifest on status: "complete".

Response — complete

{
  "job_id": "job_8Pm3nKqRsT",
  "status": "complete",
  "analysis_seconds": 4.2,
  "coverage_summary": {
    "total_bins": 12847,
    "covered_bins": 11203,
    "uncovered_bins": 1644,
    "coverage_pct": 87.2
  },
  "recommendations": [
    {
      "rank": 1,
      "test_scenario": "lsu_buffer_misaligned_access_edge",
      "target_module": "lsu_buffer",
      "confidence": 0.94,
      "coverage_bins_hit": ["misaligned_word_rd", "misaligned_dword_wr"],
      "suggested_constraints": {
        "addr_alignment": "non_aligned",
        "access_size": ["word", "dword"]
      },
      "rtl_path": "lsu_buffer.sv:147-183"
    }
  ]
}

GET /projects

List all projects accessible with your API key.

{
  "projects": [
    {
      "id": "proj_4xMv9kLpQr",
      "name": "my-chip-rtl",
      "tier": "explore",
      "created_at": "2026-03-14T09:22:00Z",
      "last_analysis": "2026-06-20T14:05:33Z",
      "analysis_count": 7
    }
  ]
}

DELETE /projects/{id}

Permanently delete a project and all associated analysis history. Irreversible.

HTTP 204 No Content