# List Intel

`GET /v3/intel`

Discrete evidence-graded developments. `grades` filters on the
evidence ladder from `chipped` to `flawless`. Project filters combine
with AND across kinds and OR within one comma-separated value.

`search` is free-text search: the query parses into meaningful terms
that must all match, against project identity (names, tickers,
handles, addresses, chains) and intel text. Matched items carry a
`searchMatches` array explaining each match. Search results page
through `meta.nextCursor`. Every non-empty query shape is accepted.
When responsive candidate or recent-result bounds may omit matches,
`meta.searchCoverage` names the bound and `meta.executedSearch`
discloses any normalized scope that differs from the request.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "$ref": "#/components/parameters/Cursor"
  },
  {
    "$ref": "#/components/parameters/Limit"
  },
  {
    "name": "search",
    "in": "query",
    "description": "Free-text deep search; combines with every other filter.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "sort",
    "in": "query",
    "description": "`detectedAt` orders by first sighting; `reinforcedAt` by the\nlatest confirming observation of any kind (an echoed story).\n",
    "schema": {
      "type": "string",
      "enum": [
        "reinforcedAt",
        "detectedAt"
      ],
      "default": "detectedAt"
    }
  },
  {
    "name": "projectIds",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "projectSlugs",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "names",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "xHandles",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "tickers",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "address",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "assetTypes",
    "in": "query",
    "description": "Comma-separated asset types of the parent Project.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "marketCap",
    "in": "query",
    "description": "Restrict to Projects whose current market cap is in the named band: `low` (under $80M), `mid` ($80M to $500M), or `large` ($500M and above). Projects without a current market cap are excluded. The band is a filter only; responses carry no market data.",
    "schema": {
      "type": "string",
      "enum": [
        "low",
        "mid",
        "large"
      ]
    }
  },
  {
    "name": "projectRanking",
    "in": "query",
    "description": "Restrict to Projects in the named ranking cohort.",
    "schema": {
      "type": "string",
      "enum": [
        "trend"
      ]
    }
  },
  {
    "name": "clusterIds",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "categories",
    "in": "query",
    "description": "Comma-separated intel event categories (see `/v3/vocabulary`).",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "grades",
    "in": "query",
    "description": "Comma-separated evidence grades.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "sentiments",
    "in": "query",
    "description": "Comma-separated sentiment values.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "hasOfficialSource",
    "in": "query",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "minClusters",
    "in": "query",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  {
    "name": "detectedAfter",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "detectedBefore",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "reinforcedAfter",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "reinforcedBefore",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "activity",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "all",
        "observations",
        "none"
      ],
      "default": "all"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Intel page.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Intel"
              }
            },
            "meta": {
              "$ref": "#/components/schemas/IntelCollectionMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Recent graded intel",
            "value": {
              "data": [
                {
                  "id": "6890aa000000000000000001",
                  "headline": "Mainnet v2 date confirmed",
                  "description": "ExampleChain confirmed the v2 mainnet date for September 3rd with a public changelog entry.",
                  "grade": "polished",
                  "project": {
                    "id": "665f0a2b1c9d440000a1b2c3",
                    "slug": "examplechain",
                    "name": "ExampleChain"
                  },
                  "category": "product-launch",
                  "clusters": [
                    {
                      "id": "cl_defi",
                      "name": "DeFi researchers"
                    }
                  ],
                  "observationCount": 9,
                  "hasOfficialSource": true,
                  "citations": [
                    "https://blog.example.chain/v2-mainnet"
                  ],
                  "sentiment": {
                    "value": "positive"
                  },
                  "detectedAt": "2026-08-04T21:14:00Z",
                  "reinforcedAt": "2026-08-05T03:40:00Z"
                }
              ],
              "meta": {
                "nextCursor": "b3BhcXVlLWN1cnNvcg",
                "history": {
                  "lookbackDays": 90,
                  "earliestAvailableAt": "2026-05-07T00:00:00Z"
                }
              }
            }
          },
          "empty": {
            "summary": "No intel matched the qualifiers",
            "value": {
              "data": [],
              "meta": {
                "nextCursor": null
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

## Referenced schemas

```json
{
  "Intel": {
    "type": "object",
    "required": [
      "id",
      "description",
      "grade",
      "project",
      "category",
      "observationCount",
      "hasOfficialSource",
      "citations",
      "detectedAt",
      "reinforcedAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "headline": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "grade": {
        "$ref": "#/components/schemas/Grade"
      },
      "project": {
        "$ref": "#/components/schemas/ProjectRef"
      },
      "category": {
        "type": "string",
        "description": "Intel event category (a vocabulary distinct from Project taxonomy)."
      },
      "clusters": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/ClusterRef"
        }
      },
      "observationCount": {
        "type": "integer"
      },
      "hasOfficialSource": {
        "type": "boolean"
      },
      "officialSourceUrl": {
        "type": "string",
        "format": "uri",
        "description": "Canonical official X provenance for the intel, including research-only observations omitted from activity."
      },
      "citations": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "description": "Vetted non-X citations supporting this intel."
      },
      "sentiment": {
        "$ref": "#/components/schemas/Sentiment"
      },
      "detectedAt": {
        "type": "string",
        "format": "date-time"
      },
      "reinforcedAt": {
        "type": "string",
        "format": "date-time",
        "nullable": true,
        "description": "Null until the first attention-contributing source activates the gem."
      },
      "activity": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/IntelActivity"
        }
      },
      "searchMatches": {
        "type": "array",
        "description": "Present only on an active `search`: why this item matched,\nderived from stored data.\n",
        "items": {
          "type": "object",
          "required": [
            "kind",
            "term"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "contract_address",
                "canonical_chain",
                "current_official_x_handle",
                "project_identity",
                "asset_profile",
                "current_official_x_profile",
                "project_profile",
                "intel_text"
              ]
            },
            "term": {
              "type": "string"
            },
            "excerpt": {
              "type": "string",
              "description": "Short public text containing the match, when it is not already visible."
            }
          }
        }
      }
    }
  },
  "Grade": {
    "type": "string",
    "enum": [
      "chipped",
      "flawed",
      "cut",
      "polished",
      "flawless"
    ],
    "description": "Evidence grade of an Intel item, lowest to highest. Grades describe\nthe shape of the evidence, never the truth of the claim.\n"
  },
  "ProjectRef": {
    "type": "object",
    "required": [
      "id",
      "slug",
      "name"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "slug": {
        "type": "string",
        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
        "maxLength": 64
      },
      "name": {
        "type": "string"
      }
    }
  },
  "ClusterRef": {
    "type": "object",
    "required": [
      "id",
      "name"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "Sentiment": {
    "type": "object",
    "required": [
      "value"
    ],
    "properties": {
      "value": {
        "type": "string",
        "enum": [
          "positive",
          "neutral",
          "negative"
        ]
      }
    }
  },
  "IntelActivity": {
    "type": "object",
    "required": [
      "action",
      "detectedAt",
      "occurredAt"
    ],
    "description": "One entry in the intel evidence trail. Detection time records when the\nsource was observed; event time records when the source claims the\nevent happened.\n",
    "properties": {
      "action": {
        "type": "string",
        "enum": [
          "observation",
          "official_statement",
          "correction",
          "merge"
        ]
      },
      "detectedAt": {
        "type": "string",
        "format": "date-time",
        "description": "Source observation timestamp."
      },
      "occurredAt": {
        "type": "string",
        "format": "date-time",
        "deprecated": true,
        "x-successor": "#/components/schemas/IntelActivity/properties/detectedAt",
        "description": "Deprecated legacy timestamp: provider publication when known, otherwise detectedAt. Use eventTime for claimed event time."
      },
      "eventTime": {
        "$ref": "#/components/schemas/IntelEventTime"
      },
      "headline": {
        "type": "string"
      },
      "source": {
        "type": "object",
        "required": [
          "url",
          "official"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "official": {
            "type": "boolean"
          }
        }
      },
      "sentiment": {
        "$ref": "#/components/schemas/Sentiment"
      },
      "clusters": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/ClusterRef"
        }
      }
    }
  },
  "IntelEventTime": {
    "description": "Claimed event time, sanitized from internal source evidence.",
    "oneOf": [
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "at",
          "precision",
          "relationToSource"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "instant"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "precision": {
            "type": "string",
            "enum": [
              "instant",
              "day",
              "week",
              "month"
            ]
          },
          "relationToSource": {
            "type": "string",
            "enum": [
              "current",
              "historical",
              "future"
            ]
          }
        }
      },
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "startAt",
          "endAt",
          "precision",
          "relationToSource"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "interval"
          },
          "startAt": {
            "type": "string",
            "format": "date-time"
          },
          "endAt": {
            "type": "string",
            "format": "date-time",
            "description": "Exclusive boundary after the final supported period."
          },
          "precision": {
            "type": "string",
            "enum": [
              "day",
              "week",
              "month"
            ]
          },
          "relationToSource": {
            "type": "string",
            "enum": [
              "current",
              "historical",
              "future"
            ]
          }
        }
      },
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "relationToSource"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "relative_unresolved"
          },
          "relationToSource": {
            "type": "string",
            "enum": [
              "before_post",
              "after_post",
              "around_post"
            ]
          }
        }
      },
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "reason"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "unknown"
          },
          "reason": {
            "type": "string",
            "enum": [
              "not_stated",
              "ambiguous",
              "ongoing"
            ]
          }
        }
      }
    ]
  },
  "IntelCollectionMeta": {
    "allOf": [
      {
        "$ref": "#/components/schemas/CollectionMeta"
      },
      {
        "type": "object",
        "properties": {
          "searchCoverage": {
            "type": "string",
            "enum": [
              "bounded_candidates",
              "bounded_recent",
              "bounded_candidates_recent"
            ],
            "description": "Responsive search bounds that may have omitted matching Intel."
          },
          "searchQuery": {
            "type": "string",
            "description": "Normalized search requested by the caller."
          },
          "executedSearch": {
            "type": "string",
            "description": "Exact normalized term scope executed by bounded search."
          }
        }
      }
    ]
  },
  "CollectionMeta": {
    "allOf": [
      {
        "$ref": "#/components/schemas/Meta"
      },
      {
        "type": "object",
        "required": [
          "nextCursor"
        ],
        "properties": {
          "nextCursor": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cursor for the next page; `null` on the last page."
          }
        }
      }
    ]
  },
  "Meta": {
    "type": "object",
    "description": "Response metadata. Empty when nothing applies.",
    "properties": {
      "history": {
        "$ref": "#/components/schemas/HistoryMeta"
      },
      "versions": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "Named component versions that shaped this response."
      }
    }
  },
  "HistoryMeta": {
    "type": "object",
    "description": "The history window applied to this response. Both fields are null when the account has no history limit.",
    "required": [
      "lookbackDays",
      "earliestAvailableAt"
    ],
    "properties": {
      "lookbackDays": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ]
      },
      "earliestAvailableAt": {
        "oneOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ]
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).