Public evidence assessments

Use the server-to-server boundary

Public evidence assessments inspect submitted public URLs using a versioned Concierge profile. They do not collect applicant email, require Concierge on the submitted website, or make approval, rejection, ranking, certification, verification, or promotion decisions.

1. 1Open the site's Developer access page in Concierge.
2. 2Create a key with only assessments:write and assessments:read.
3. 3Copy the generated secret once and store it in a server-side secret manager.
4. 4Queue the assessment with a stable idempotency-key header.
5. 5Store the returned assessmentId and poll until status is completed or failed.

export CONCIERGE_API_URL="https://concierge-backend-gik7.onrender.com"
export CONCIERGE_SITE_ID="site_c51bd922042e35f7"
export CONCIERGE_ASSESSMENT_API_KEY="cg_live_..."
export CONCIERGE_ASSESSMENT_PROFILE="catalogue-listing-review"

Queue an assessment

POST returns the durable assessment ID after successful queueing. Retrieval runs asynchronously; queued and running phases describe work the backend has actually reached.

curl --fail-with-body -X POST \
  "$CONCIERGE_API_URL/v1/sites/$CONCIERGE_SITE_ID/assessments" \
  -H "Content-Type: application/json" \
  -H "x-concierge-api-key: $CONCIERGE_ASSESSMENT_API_KEY" \
  -H "idempotency-key: altnative-assessment-<local-assessment-id>" \
  --data '{
    "profileKey": "catalogue-listing-review",
    "externalReference": "<product-id>",
    "subject": {
      "type": "developer_tool",
      "name": "Example",
      "description": "Submitted public description",
      "urls": [
        { "type": "website", "url": "https://example.com" },
        { "type": "documentation", "url": "https://docs.example.com" },
        { "type": "repository", "url": "https://github.com/example/example" }
      ],
      "claims": {
        "pricingModel": "freemium",
        "freeTier": true,
        "openSource": false,
        "platforms": ["web", "api"],
        "integrations": ["Slack"]
      }
    }
  }'

Poll without inventing progress

Treat queued and running as active. Stop polling on completed or failed. The profileVersion identifies the immutable rules snapshot used for the assessment; cited evidence contains short normalized facts and public URLs rather than retained page bodies.

• 401 means the key is missing, invalid, or revoked.
• 403 means the key lacks the required assessment scope or the profile is inactive.
• 404 does not reveal whether another site's assessment exists.
• 429 means the per-site queue limit was reached; honor the response and retry later.
• A failed assessment returns a safe failureMessage and can be retried by an authorized operator.
• Applicant and moderator-only visibility is configured in the versioned profile; the caller remains responsible for its own presentation boundary.

curl --fail-with-body \
  "$CONCIERGE_API_URL/v1/sites/$CONCIERGE_SITE_ID/assessments/$ASSESSMENT_ID" \
  -H "x-concierge-api-key: $CONCIERGE_ASSESSMENT_API_KEY"

Retention and deletion

Each assessment receives a deletion date from the immutable profile retention policy. Platform operators can delete an assessment earlier with a recorded reason. Retry and deletion never change catalogue decisions because Concierge does not own them.