The evidence API

Register plots

The country names the region a finding is reported against and drives the axis-order check. A feature's own country property wins over it.

curl -X POST "https://lisaris.axinelabs.com/api/v1/portal/plots/import?country=CI" \
  -H "Authorization: Bearer $AXINE_KEY" \
  -F "file=@plots.geojson"

Run evidence

Name the plots, or send {"all": true} for every valid plot not yet read. The answer carries the job id and how much of the allowance is used.

curl -X POST "https://lisaris.axinelabs.com/api/v1/portal/plots/evidence" \
  -H "Authorization: Bearer $AXINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plot_ids": ["3f6c2a9e-0d4b-4c1e-9a77-1b2c3d4e5f60"]}'

Fetch results per plot

The JSON and the PDF come from one stored object, so they cannot disagree. Before the read finishes both answer 409 no_evidence with the plot's state.

curl "https://lisaris.axinelabs.com/api/v1/portal/plots/3f6c2a9e-0d4b-4c1e-9a77-1b2c3d4e5f60/evidence" \
  -H "Authorization: Bearer $AXINE_KEY"

curl -o evidence.pdf \
  "https://lisaris.axinelabs.com/api/v1/portal/plots/3f6c2a9e-0d4b-4c1e-9a77-1b2c3d4e5f60/evidence.pdf" \
  -H "Authorization: Bearer $AXINE_KEY"

Bulk and asynchronous

Where the whole book stands: plots by state and by result, the allowance used, and the register a page at a time.

curl "https://lisaris.axinelabs.com/api/v1/portal/plots/evidence/summary" \
  -H "Authorization: Bearer $AXINE_KEY"

curl "https://lisaris.axinelabs.com/api/v1/portal/plots?limit=100&offset=0" \
  -H "Authorization: Bearer $AXINE_KEY"

Webhooks on completion

Leave events out to receive all of them. The signing secret is in this answer and nowhere after it; the test call sends an event now and returns what your server answered.

curl -X POST "https://lisaris.axinelabs.com/api/v1/portal/webhooks" \
  -H "Authorization: Bearer $AXINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/axine/events",
       "events": ["plot.evidence.completed", "plot.evidence.failed"]}'

curl -X POST "https://lisaris.axinelabs.com/api/v1/portal/webhooks/<endpoint id>/test" \
  -H "Authorization: Bearer $AXINE_KEY"

curl "https://lisaris.axinelabs.com/api/v1/portal/webhooks/deliveries" \
  -H "Authorization: Bearer $AXINE_KEY"

import hashlib
import hmac
import time


def verify(secret: str, body: bytes, timestamp: str, signature: str,
           tolerance: int = 300) -> bool:
    """True when the delivery is ours and was sent within five minutes."""
    try:
        if abs(time.time() - int(timestamp)) > tolerance:
            return False
    except (TypeError, ValueError):
        return False
    signed = timestamp.encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(part.strip()[3:], expected)
               for part in signature.split(",")
               if part.strip().startswith("v1="))


# In your handler, with the raw body as received, before parsing it:
# ok = verify(SECRET, request.body, request.headers["X-Axine-Timestamp"],
#             request.headers["X-Axine-Signature"])

const crypto = require("crypto");

function verify(secret, rawBody, timestamp, signature, tolerance = 300) {
  const ts = Number(timestamp);
  if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > tolerance) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${timestamp}.`).update(rawBody).digest();
  return String(signature).split(",").map((s) => s.trim())
    .filter((s) => s.startsWith("v1="))
    .some((s) => {
      const got = Buffer.from(s.slice(3), "hex");
      return got.length === expected.length && crypto.timingSafeEqual(got, expected);
    });
}

// Express: keep the raw body, check it, then parse it.
// app.post("/axine/events", express.raw({ type: "application/json" }), (req, res) => {
//   if (!verify(SECRET, req.body, req.get("X-Axine-Timestamp"), req.get("X-Axine-Signature")))
//     return res.sendStatus(400);
//   res.sendStatus(204);
//   const event = JSON.parse(req.body);
// });

module.exports = { verify };