Skip to content
Start a project Sign in
API Reference

One endpoint to a decision.

Send a person and a context. Get back a match, a score and a reason you can print — in in a single call.

base url api.specicon.com/v1 auth Bearer key format JSON p99 target
One call, one reasoned answer

A decision endpoint, not a search box.

Post the customer, the need and the constraints. Get back ranked options, a confidence and the reasons behind them.

Specicon filmno audio
Quickstart

First match in five minutes.

01

Get a key

Keys are issued per environment during your working session — sandbox first, production at go-live.

02

POST /v1/match

Send a user reference and any context you have. Identity resolution happens server-side.

03

Ship the reason too

The reason string is written for humans. Render it next to the match — that's where trust comes from.

curl 
curl -X POST https://api.specicon.com/v1/match \
  -H "Authorization: Bearer $SPECICON_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user":    "barcode_id",
    "context": { "occasion": "date_night" }
  }'
POST /v1/match

The core decision call. Resolves the user's identity, matches it against Product DNA, ranks against your objective, and returns the winner with its reason.

Request fields
userstringYour user reference — we resolve it to a User Barcode™.
contextobjectOccasion, channel, budget band — anything the moment knows.
objectivestringOptional ranking objective: conversion (default), margin, retention.
candidatesintHow many ranked matches to return. Default 1, max 10.
Response fields
matchstringThe winning product reference.
scorefloatFit confidence, 0–1. Gate low-confidence surfaces on it.
reasonstringThe human-readable why. Same string on every surface.
Request POST /v1/match 
{
  "user":       "usr_48213",
  "context":    { "occasion": "date-night", "budget_band": "100-150" },
  "objective":  "conversion",
  "candidates": 1
}
200 OK 
{
  "match":      "Oud Velvet Noir",
  "score":      0.94,
  "reason":     "warm · evening · luxury — date-night optimal",
  "confidence": "high",
  "latency_ms": 18
}
GET/v1/identity/{user}

Inspect a resolved User Barcode™: dimension values (warmth, intent, value…), stability, and when it last updated. Useful for debugging and for your own dashboards.

POST/v1/feedback

Close the loop: send outcomes — accepted, converted, returned — and the feedback engine tunes future ranking. This is what makes week ten better than week one.

Errors

Predictable, explained failures.

401Missing or invalid API key.
404Unknown user or product reference.
422Context didn't validate — the error body names the field.
429Rate limit reached — headers carry your reset time.
Limits & environments

Scaled to your tier.

Rate limits and quotas follow your plan — Launch covers a pilot surface comfortably; Expand and Enterprise raise ceilings and add regional endpoints. Every plan gets a full-fidelity sandbox.

Every response carries the decision's latency and a request id, so your observability sees what ours sees.

Compare tiers