# List shared model references

```http
GET /api/public/v1/contributor-network/items
```

**Scope**: `contributor-network.read`.

Lists active Contributor Network model references for the Modular Arithmetic Challenge. Send both fixed discriminator filters so every item has the model-reference summary shape documented on this page.

Withdrawn, hidden, deleted, or force-revoked items are never returned. The pinned Hugging Face commit is omitted from this collection; fetch one item when the exact revision is needed. Reading the public collection requires neither competition enrollment nor a Competition Team and is independent of the formal-submission window.

The requested competition must be publicly visible as active or closed and must expose `capabilities.contributorNetwork: true`. A draft, missing, or unsupported competition returns `404 NOT_FOUND`.

## Query parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :---: | :--- | :--- |
| `competitionId` | string | Yes | — | Must be `modular-arithmetic-challenge`. |
| `kind` | string | Yes | — | Must be `model-reference`. |
| `scope` | string | No | `all` | `all`, `mine`, or `favorites`. |
| `search` | string | No | — | Trimmed, non-empty text of at most 200 characters. Matches public author, model name, remark, or pinned commit hash. |
| `publicCode` | string | No | — | Exact public-code filter after trimming and case normalization. |
| `sort` | string | No | `newest` | `newest` or `earliest`. |
| `cursor` | string | No | — | Opaque cursor from the previous `nextCursor`. |
| `limit` | integer | No | `25` | Page size from `1` through `100`. |

`scope=mine` selects items authored by the calling account. `scope=favorites` selects items the calling account has favorited. `search` is a case-insensitive substring match over public author display name, model name, remark, and pinned commit hash. It does not fetch or search external repository contents.

When `publicCode` is present, the response contains at most one item and `nextCursor` is always `null`; do not combine it with `cursor`. A code that does not identify an active model reference matching the other filters returns an empty collection.

## Ordering and pagination

`newest` orders by `publishedAt` descending; `earliest` orders ascending. Item ID is the stable tie-breaker in both directions. Filters are applied before pagination. Reuse a cursor only with the same filters and sort order, as described in [Pagination](../../../pagination.md).

## Example request

```bash
curl "https://api.sair.foundation/api/public/v1/contributor-network/items?competitionId=modular-arithmetic-challenge&kind=model-reference&limit=25" \
  -H "Authorization: Bearer $SAIR_API_KEY"
```

## Response fields

| Field | Type | Description |
| :--- | :--- | :--- |
| `items` | [ContributorModelSummary](#summary-fields)[] | Model-reference summaries. Fetch one item for its exact pinned revision and lineage references. |
| `nextCursor` | string \| null | Cursor for the next page, or `null` after the final page. |

### Summary fields

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | string | Stable Contributor Network item ID. |
| `publicCode` | string | Immutable, globally unique code intended for sharing and lookup. |
| `competitionId` | string | Always `modular-arithmetic-challenge`. |
| `kind` | string | Always `model-reference`. |
| `title` | string | Published Hugging Face model name. Use `id`, not this display value, as the resource identifier. |
| `remark` | string \| null | Optional publication note. |
| `author.sairId` | string | Public SAIR account ID. |
| `author.displayName` | string | Display name snapshotted for the publication. |
| `author.avatarUrl` | string \| null | Public avatar URL, or `null` when absent. |
| `contentBytes` | integer | UTF-8 byte length of the canonical `modelName@commitHash` reference string; not the external model size. |
| `contentSha256` | string | Lowercase SHA-256 digest of that canonical reference string. |
| `favoriteCount` | integer | Accounts currently favoriting the item. |
| `viewerHasFavorited` | boolean | Whether the calling account has favorited the item. |
| `commentCount` | integer | Visible comments currently attached to the item. |
| `directChildCount` | integer | Active model references that directly cite this item as their parent. |
| `publishedAt` | string | ISO 8601 UTC publication time. |

Model-reference summaries omit unrelated Stage 2 `track` and `modelId` fields instead of returning them as `null`.

## Example response

```json
{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "cn_01JMODULAR0000000000000001",
        "publicCode": "MAC01-000042",
        "competitionId": "modular-arithmetic-challenge",
        "kind": "model-reference",
        "title": "your-team/modular-solver",
        "remark": "Pinned revision used for public comparison.",
        "author": {
          "sairId": "U-9f7e1c00",
          "displayName": "alice",
          "avatarUrl": null
        },
        "contentBytes": 65,
        "contentSha256": "bf18f581ed57f05b4aac5af249017bd371991bbca1d5002fac7fc32612b01604",
        "favoriteCount": 2,
        "viewerHasFavorited": false,
        "commentCount": 1,
        "directChildCount": 0,
        "publishedAt": "2026-06-08T09:00:00Z"
      }
    ],
    "nextCursor": null
  }
}
```

An empty match returns `items: []` and `nextCursor: null` with `200 OK`.

## Errors

| HTTP | Code | When |
| :---: | :--- | :--- |
| `400` | `MALFORMED_BODY` | `cursor` is invalid or `limit` is outside its allowed range. |
| `404` | `NOT_FOUND` | The requested competition is unavailable or does not expose model references. |
| `422` | `RESOURCE_FIELD_INVALID` | A discriminator, scope, search, sort, public code, or query-parameter combination is invalid. |

See [Errors](../../../errors.md) for authentication, scope, and rate-limit errors.