Search titles

GET

/titles

const url = 'https://api.doesitarm.com/v1/titles?query=photoshop&kind=app&limit=50';
const options = {method: 'GET'};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.doesitarm.com/v1/titles?query=photoshop&kind=app&limit=50'

Resolve a fuzzy query to ranked candidate titles, each with its best-known status. This is the disambiguation surface; GET /verdicts/{identifier} is the cacheable answer surface. Search never returns 409 — ambiguity is its normal 200.

Mirrors the MCP tool search_titles.

Authorizations

None
ApiKeyAuth

Parameters

Query Parameters

query

required

string

The search string.

Example

photoshop

kind

string

Allowed values: app game

Restrict to apps or games.

limit

integer

default: 50 >= 1 <= 100

Page size (default 50, max 100).

cursor

string

Opaque pagination cursor from the previous page’s pagination.nextCursor. Do not parse it.

Responses

200

Ranked candidate titles.

application/json

A page of search results.

object

data

required

Array<object>

One candidate from a search, with its best-known status and a match score.

object

slug

required

string

title

required

string

kind

required

string

Allowed values: app game

status

Best-known status for the candidate (may be unknown).

string

Allowed values: native rosetta2 translation unsupported unknown

score

required

Match score from 0 to 1.

number format: float

pagination

required

Cursor-based pagination envelope. The cursor is opaque — never parse it.

object

nextCursor

required

Opaque cursor for the next page; null at the end.

string | null

hasMore

required

boolean

Example

{
  "data": [
    {
      "slug": "figma",
      "title": "Figma",
      "kind": "app",
      "status": "native",
      "score": 0.97
    },
    {
      "slug": "figment",
      "title": "Figment",
      "kind": "app",
      "status": "unknown",
      "score": 0.41
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore": false
  }
}

Headers

RateLimit-Limit

integer

Requests allowed in the current window.

RateLimit-Remaining

integer

Requests left in the current window.

RateLimit-Reset

integer

Seconds until the window resets (IETF ratelimit-headers, pre-08 three-header form).

422

A parameter was invalid. (HTTP 422.)

application/json

The single error envelope used by every 4xx/5xx. Agents branch on code; humans read message. No 3xx ever carries this body.

object

error

required

object

type

required

Coarse family. (‘ambiguous’ is a code, carried under type invalid_request.)

string

Allowed values: invalid_request rate_limited auth server

code

required

Fine-grained branch value.

string

Allowed values: ambiguous invalid_param auth_required auth_invalid plan_required rate_limited internal

message

required

Human-readable explanation.

string

docsUrl

string format: uri

upgradeUrl

string format: uri

suggestions

Present on ambiguous — candidate titles to disambiguate with.

Array<object>

object

slug

required

string

title

required

string

score

number format: float

requestId

required

Quote this to support.

string

Example

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_param",
    "message": "Unknown chip 'm9'. Allowed: apple_silicon, m1, m2, m3, m4.",
    "docsUrl": "https://docs.doesitarm.com/api/errors/",
    "requestId": "req_01J5K6Q8ZA"
  }
}

429

Rate limit exceeded. (HTTP 429.)

application/json

The single error envelope used by every 4xx/5xx. Agents branch on code; humans read message. No 3xx ever carries this body.

object

error

required

object

type

required

Coarse family. (‘ambiguous’ is a code, carried under type invalid_request.)

string

Allowed values: invalid_request rate_limited auth server

code

required

Fine-grained branch value.

string

Allowed values: ambiguous invalid_param auth_required auth_invalid plan_required rate_limited internal

message

required

Human-readable explanation.

string

docsUrl

string format: uri

upgradeUrl

string format: uri

suggestions

Present on ambiguous — candidate titles to disambiguate with.

Array<object>

object

slug

required

string

title

required

string

score

number format: float

requestId

required

Quote this to support.

string

Example

{
  "error": {
    "type": "rate_limited",
    "code": "rate_limited",
    "message": "Free tier allows 60 requests/min. Retry in 30s or upgrade.",
    "docsUrl": "https://docs.doesitarm.com/api/rate-limits/",
    "upgradeUrl": "https://doesitarm.com/early-access",
    "requestId": "req_01J5K6Q8ZD"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying. Sent on 429.

RateLimit-Limit

integer

Requests allowed in the current window.

RateLimit-Remaining

integer

Requests left in the current window.

RateLimit-Reset

integer

Seconds until the window resets (IETF ratelimit-headers, pre-08 three-header form).