Check an action before your software carries it out.

1. Choose the right endpoint and key

REST requests use POST and Content-Type: application/json. Direct PROME keys and RapidAPI keys are not interchangeable. Keep keys in backend secret storage, not browser JavaScript, prompts, URLs or logs. Choose a RapidAPI plan, or contact PROME for direct pilot access.

Contract 2 also requires trusted-host registration. Register your backend to receive its issuer ID, customer binding and signing key, and agree its allowed actors, resource/operation/destination scopes and protected systems. Do not derive the customer binding from your RapidAPI key. Registration is currently a separate onboarding step, not automatic with a subscription.

The API key buys/accesses checks. The separate signing key attests that your registered backend supplied the facts. Neither establishes legal ownership or proves that a prediction is true. Your backend must verify access to the exact record; registration scopes cover resource, operation and destination, while the signature binds the exact record too.

2. Make a harmless first call

Download the complete synthetic request to request.json. It has evidence: null. With a valid API key, it should return needs_review, not a pass. This proves the unsigned-request boundary works; it is not a failure of the product. The example controls no real system.

curl --fail-with-body --max-time 30 \
  https://prome.ai/api/guardrail \
  -H "Authorization: Bearer $PROME_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @request.json

For RapidAPI, use its REST URL and two headers from the table instead. The variable above must already contain your private key; do not paste a real key into a shared command or enable shell tracing. Never follow redirects with credentials. Curl does not follow redirects unless requested.

Expected hold reasons: evidence_source_not_registered before registration, or signed_evidence_required for a registered customer. Without a valid access key, expect an authentication error instead. Gateway calls may count toward your RapidAPI allowance even when they hold or fail.

3. Supply complete facts, not a prompt

All fields in the contract-2 JSON Schema are required; unknown fields are rejected. IDs use 1–64 letters, digits, underscores or hyphens. Use internal identifiers, not personal data, URLs or secrets.

Every baseline situation and action outcome

Supply id, entities, catastrophe, resource_loss, undo_cost, danger, service_loss and duration. Every action must contain exactly the same situation IDs and entity IDs as the baseline. Every situation must cover the same 1–32 entities. Missing possibilities in the real world are not discovered by the API.

• Each entity needs id, harm, irreversible (lasting harm), and wellbeing.
• catastrophe is a JSON boolean. Other measurements are exact integer or fraction strings, for example "0", "3" or "1/2"—not decimal strings or JSON numbers.
• Numerators and denominators have at most 15 digits. Denominators must be positive; only wellbeing may be negative. Do not use NaN, infinity or scientific notation.
• Choose documented, validated units for each measure and keep them consistent between baseline, options and comparable entities. There is no universal conversion from a prompt to a calibrated harm score. Never fill unknown effects with zero to obtain a pass.

Every action

Use the same meaning for each measure throughout the request:

The exact operation and its flags

tool contains exactly resource, operation, destination and record. These are IDs, not executable code or arbitrary arguments. Your executor must map them to one exact operation without reinterpreting them.

Supply four real booleans: changes_core, retaliation, stops_attack, ends_with_attack. The last two remain required in ordinary mode, although the defensive checks apply only in defensive mode. Changing values or retaliating is rejected in either mode.

REST bodies are limited to 64 KiB. MCP allows its protocol envelope separately, but the facts object must still fit within 64 KiB. Contract 2 permits 16 actions, 8 situations and 32 entities—do not use the older contract-1 limits.

4. Sign only from your trusted backend

Keep the 32-byte HMAC-SHA256 key private. It is supplied as 64 hexadecimal characters, not the API key. Do not give an AI agent a tool that will blindly sign whatever it requests. Validate the underlying observations and record-level permission before signing.

Use Unix seconds with synchronized clocks. Evidence must satisfy issued_at <= now < expires_at, with a positive lifetime of at most 60 seconds. There is no future-clock grace period. If it expires, construct a new check with a new ID and newly validated facts.

This Python 3 signing function uses only the standard library. It matches PROME's canonical format: sorted keys, no spaces, ASCII escaping, UTF-8 encoding, and no non-finite numbers. Other languages must reproduce those bytes exactly; ordinary JSON.stringify alone is not equivalent. Ask for an interoperability check during registration.

import copy, hashlib, hmac, json, re

def canonical(value):
    return json.dumps(value, sort_keys=True, separators=(",", ":"),
                      ensure_ascii=True, allow_nan=False).encode("utf-8")

def sign_request(facts, customer_binding, secret_hex):
    if not re.fullmatch(r"[0-9a-f]{64}", secret_hex):
        raise ValueError("Use the registered 32-byte signing key in hex")
    unsigned = copy.deepcopy(facts)
    unsigned["evidence"].pop("signature", None)
    message = {"audience": "prome-care-core-contract-2",
               "customer": customer_binding, "request": unsigned}
    return hmac.new(bytes.fromhex(secret_hex), canonical(message),
                    hashlib.sha256).hexdigest()

Before calling it, set a new request ID and the evidence envelope below. Use the issuer and customer binding supplied by PROME—not values invented by the agent. Then set facts["evidence"]["signature"] = sign_request(facts, customer_binding, secret_hex). Send that exact request using the REST URL and credentials above.

{"issuer":"YOUR_REGISTERED_ISSUER","issued_at":CURRENT_UNIX_SECONDS,
 "expires_at":CURRENT_UNIX_SECONDS_PLUS_60,"signature":""}

This envelope is a template, not executable JSON until its time placeholders are replaced by integers and the signature is computed. Host revocation/configuration changes currently require deployment; this is not an instant emergency-stop service. Evidence expiration is not a replacement for a separate actuator safety system.

5. Connect an agent through MCP

Use a client supporting Streamable HTTP and custom Authorization headers, with the direct or subscription MCP URL above. This is key-based access, not OAuth. Initialize using the client's supported protocol negotiation, complete its initialized notification, then call tools/list.

For contract 2, select care_core_check_signed_actions. The tool takes one field, facts, containing the complete signed REST request. Do not send only a prompt or flatten the request into the tool arguments. The older care_core_check_actions remains for legacy compatibility.

{"jsonrpc":"2.0","id":"call-1","method":"tools/call",
 "params":{"name":"care_core_check_signed_actions",
           "arguments":{"facts": COMPLETE_SIGNED_REQUEST_OBJECT}}}

This is an envelope template: replace COMPLETE_SIGNED_REQUEST_OBJECT with the JSON object, not a quoted JSON string. The protocol call ID (call-1) is separate from facts.request_id, which controls retries and accounting. For manual HTTP clients, send Accept: application/json, text/event-stream and Content-Type: application/json, plus the negotiated MCP protocol header after initialization.

Read result.structuredContent for the decision. First check for a JSON-RPC error or result.isError: true. A legitimate hold has isError: false but decision: "needs_review". Tool discovery alone does not verify a RapidAPI subscription; the first check does. Agents must not retry a hold until the underlying facts or permissions are resolved.

6. Read the result without turning advice into permission

See full JSON examples: pass, permission hold and missing evidence. These are actual outputs from synthetic local fixtures, not live customer records. Their timestamps are deliberately historical: never treat these examples as current permission.

REST returns the object directly; MCP places it in result.structuredContent. There is no bare 1/0 response. HTTP 200 means the request was processed, not that the action passed.

Common reasons

• ordered_selection: one option won the implemented comparison.
• no_eligible_action: every option failed a check; inspect rejected.
• unresolved_tie: no unique winning option. Do not choose one on PROME's behalf.
• evidence_source_not_registered, signed_evidence_required, evidence_source_not_allowed: resolve registration, issuer or actor configuration.
• evidence_signature_invalid, evidence_expired_or_not_yet_valid, evidence_revoked: stop; fix signing, clocks or revoked access.
• Rejection reasons include permission_missing_or_invalid, core_change, retaliation, catastrophe, individual_harm_increase, combined_or_irreversible_increase and defense_boundary.

Before your application even considers execution

1. Require a successful transport response with no MCP error and the expected version/policy.
2. Require passes_supplied_checks, the matching request ID, a selected ID from your original options and the exact matching tool object.
3. Compare request_sha256 with hashlib.sha256(canonical(facts)).hexdigest(), using the canonical function above.
4. Require matching, unexpired evidence. Missing or unexpected fields mean stop.
5. Independently recheck actual facts and current record-level permission. Enforce a one-time, exact-action execution gate in your own system. Never execute a replayed check twice.

A signature authenticates a source, not the truth of its predictions. Care Core cannot protect a tool that bypasses your execution gate. For robotics or other life-critical uses, this pilot is not a substitute for independently qualified safety controls.

7. Errors, retries and billing

For an exact retry, retain all fields, signature, times and request ID. Re-signing or changing any fact makes it a new request and requires a new ID. PROME's completed identical checks count once in its own ledger; RapidAPI may count every gateway request. Completed policy holds also count. Early evidence failures are not completed policy evaluations. REST and MCP share accounting for the same customer identity.

PROME stores customer/usage records, a request fingerprint and results, not raw fact bodies in its accounting ledger. Upstream gateways have their own data handling. IDs, selected tools and reasons in results can still be sensitive: keep them free of secrets and personal information.

Before you launch

• Test a permitted synthetic request, a harm increase, an outside target, altered signed facts, an expired signature and a missing key.
• Test timeouts, quota errors, changed-input retries and duplicate execution prevention.
• Document where each observation comes from, its units and how missing or uncertain effects trigger a hold.
• Confirm the agent cannot access the signing key, invent trusted measurements, or bypass the execution gate.
• Measure your own end-to-end latency, including any RapidAPI/Smithery hop. The current pilot has no uptime, maximum-latency or universal safety guarantee.

Existing contract-1 clients can continue using the legacy guide. Contract 1 uses nine numeric measurements and different limits; it does not activate contract 2's signed permission checks. Do not mix the formats.

Ask for onboarding or a signing interoperability check.