POST /logo/v1/resolve

Resolve a website logo using the selected source or named composition. A genuine miss is a 200 reply with status missing; source failures remain distinct.

Authentication: a short-lived signed token, Authorization: Bearer <token>. The audience is website-logo and the scope is logo.
Safe to repeat: yes. The client retries it after a retryable failure.
Agent tool: logo.resolve

Rules the service checks (the client sends the request as it is and the service refuses it with INVALID_INPUT):

Exactly one nonempty DNS hostname (max 253 characters) or absolute HTTP(S) URL (max 2048, no credentials). fresh bypasses the selected mode’s cache.

A code HTTP_<status> is a structured reply (see the schema in the contract), not an error body: the client reports it with that code and keeps the reply in error.body.

POST/logo/v1/resolve

Request body

requiredapplication/json

hostnamestring

Show properties

Any of:

string

string

urlstring

Show properties

Any of:

string

string

freshboolean

Show properties

Any of:

boolean

boolean

modestring

Allowed:composedmicrolinklogo-devdirect-favicon

Responses

200

Success

modestringrequired

Allowed:composedmicrolinklogo-devdirect-favicon

statusstringrequired

Allowed:foundmissing

resolutionobjectrequired

Show properties

resolvedbooleanrequired

logoUrlstring | nullrequired

Show properties

Any of:

string

string

null

null

sourcestring | nullrequired

Show properties

Any of:

string

string

null

null

hostnamestringrequired

canonicalUrlstring | nullrequired

Show properties

Any of:

string

string

null

null

redirectHostnamestring | nullrequired

Show properties

Any of:

string

string

null

null

iframeBlockedboolean | nullrequired

Show properties

Any of:

boolean

boolean

null

null

cachedbooleanrequired

imageUrlstring | nullrequired

The image served by Comms.ID (https://api.comms.id/logo/v1/image/<id>), valid for seven days; null when nothing resolved. Show this one, not logoUrl.

Show properties

Any of:

string

string

null

null

outcomesobject[]required

Show properties

Array of object

sourcestringrequired

Allowed:microlinklogo.devdirect-favicon

outcomestringrequired

Allowed:hitmisserrortimeoutskipped

codestring | nullrequired

Show properties

Any of:

string

string

null

null

400

The request body does not meet the operation input rules.

codestringrequired

Allowed:INVALID_INPUT

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

401

A valid capability for this product is required.

codestringrequired

Allowed:UNAUTHORIZED

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

403

The browser origin is not permitted for this app.

codestringrequired

Allowed:ORIGIN_NOT_ALLOWED

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

404

The requested resource was not found.

codestringrequired

Allowed:NOT_FOUND

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

405

The route does not accept this HTTP method.

codestringrequired

Allowed:METHOD_NOT_ALLOWED

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

429

The service request-rate limit was reached; wait before retrying. | The app or owner fair-use allowance is exhausted; retry after Retry-After.

Any of:

LogoError_LIMIT_REACHED

codestringrequired

Allowed:LIMIT_REACHED

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

LogoError_FAIR_USE_CEILING

codestringrequired

Allowed:FAIR_USE_CEILING

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

499

The caller cancelled the operation.

codestringrequired

Allowed:CANCELLED

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

500

The service could not complete the operation.

codestringrequired

Allowed:INTERNAL_ERROR

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

503

The selected logo source is not configured. | The selected logo mode cannot run with the available sources. | No admitted resident service is available. | No result because an eligible source failed. Safe per-source outcomes are retained.

Any of:

LogoError_CONFIGURATION_ERROR

codestringrequired

Allowed:CONFIGURATION_ERROR

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

LogoError_UNAVAILABLE_MODE

codestringrequired

Allowed:UNAVAILABLE_MODE

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

LogoError_RESIDENCY_UNAVAILABLE

codestringrequired

Allowed:RESIDENCY_UNAVAILABLE

messagestringrequired

retryablebooleanrequired

requestIdstringrequired

LogoUnavailable

modestringrequired

Allowed:composedmicrolinklogo-devdirect-favicon

statusstringrequired

Allowed:unavailable

resolutionobjectrequired

Show properties

resolvedbooleanrequired

logoUrlstring | nullrequired

Show properties

Any of:

string

string

null

null

sourcestring | nullrequired

Show properties

Any of:

string

string

null

null

hostnamestringrequired

canonicalUrlstring | nullrequired

Show properties

Any of:

string

string

null

null

redirectHostnamestring | nullrequired

Show properties

Any of:

string

string

null

null

iframeBlockedboolean | nullrequired

Show properties

Any of:

boolean

boolean

null

null

cachedbooleanrequired

outcomesobject[]required

Show properties

Array of object

sourcestringrequired

Allowed:microlinklogo.devdirect-favicon

outcomestringrequired

Allowed:hitmisserrortimeoutskipped

codestring | nullrequired

Show properties

Any of:

string

string

null

null

requestIdstringrequired

Request

curl -sS -X POST https://api.comms.id/logo/v1/resolve \
  -H "Authorization: Bearer $COMMS_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"example.com","mode":"direct-favicon"}' \
  -H "Accept: application/json"

import { createLogoClient } from "@comms-id/logo/server";

const client = createLogoClient({
  clientId: process.env.COMMS_ID_CLIENT_ID!,
  privateJwk: JSON.parse(process.env.COMMS_ID_PRIVATE_JWK!),
});
const reply = await client.resolve({
  hostname: "example.com",
  mode: "direct-favicon"
});

npx comms-id logo resolve --hostname "example.com" --mode "direct-favicon"

Response

{
  "mode": "direct-favicon",
  "status": "found",
  "resolution": {
    "resolved": true,
    "logoUrl": "https://example.com/favicon.ico",
    "source": "direct-favicon",
    "hostname": "example.com",
    "canonicalUrl": "https://example.com",
    "redirectHostname": null,
    "iframeBlocked": null,
    "cached": false,
    "imageUrl": "https://api.comms.id/logo/v1/image/ZGlyZWN0LWZhdmljb258ZXhhbXBsZS5jb218MTc5MTYzMzYwMA.c2lnbmF0dXJlLWV4YW1wbGUtc2lnbmF0dXJlLWV4YW1wbGUtMDA"
  },
  "outcomes": [
    {
      "source": "direct-favicon",
      "outcome": "hit",
      "code": null
    }
  ]
}

{
  "code": "INVALID_INPUT",
  "message": "string",
  "retryable": true,
  "requestId": "string"
}

{
  "code": "UNAUTHORIZED",
  "message": "string",
  "retryable": true,
  "requestId": "string"
}

{
  "code": "ORIGIN_NOT_ALLOWED",
  "message": "string",
  "retryable": true,
  "requestId": "string"
}

{
  "code": "NOT_FOUND",
  "message": "string",
  "retryable": true,
  "requestId": "string"
}

{
  "code": "METHOD_NOT_ALLOWED",
  "message": "string",
  "retryable": true,
  "requestId": "string"
}

{
  "code": "LIMIT_REACHED",
  "message": "string",
  "retryable": true,
  "requestId": "string"
}

{
  "code": "CANCELLED",
  "message": "string",
  "retryable": true,
  "requestId": "string"
}

{
  "code": "INTERNAL_ERROR",
  "message": "string",
  "retryable": true,
  "requestId": "string"
}

{
  "code": "CONFIGURATION_ERROR",
  "message": "string",
  "retryable": true,
  "requestId": "string"
}