repos.list() - Mesa Docs

List repositories using cursor pagination. Required scope: read

repos = await mesa.repos.list(limit=50)

for repo in repos.repos:
    print(repo.name, repo.default_bookmark, repo.head_change_id)

Options

str | None

Organization override.

str | None

Opaque pagination cursor from a previous response.

int | None

Maximum number of repositories to return. The server maximum is 100.

str | dict[str, object] | None

Filter results by repository tags. See Tag Filters below.

Tag Filters

Filter the repository list by the tags on each repository. Pass a dictionary where each key is a tag name:

await mesa.repos.list(
    tags={
        "kind": "memory",  # kind equals "memory"
        "environment": "prod",  # environment equals "prod"
        "region": ["us-east-1", "us-west-2"],  # region is either value
    }
)

A repository matches when every key matches: multiple keys in one dictionary are implicitly combined with the logical $and operator. The filter above is equivalent to:

await mesa.repos.list(
    tags={
        "$and": [{"kind": "memory"}, {"environment": "prod"}, {"region": ["us-east-1", "us-west-2"]}],
    }
)

Combine $and, $or, and $not to build more complex queries:

await mesa.repos.list(
    tags={
        "$and": [
            {"workload": {"$in": ["sync", "index"]}},
            {"$or": [{"environment": "prod"}, {"environment": "staging"}]},
            {"$not": {"lifecycle": "archived"}},  # excludes archived repos
        ]
    }
)

Operator names start with $ and are case-insensitive ($and, $AND, and $AnD are equivalent). The $ prefix is reserved for operators, so a tag name can never start with $ — but plain and, or, and not are ordinary tag names.

Value Operators

Tag values match exactly by default. Wrap the value in an operator dictionary for other comparisons:

Operator	Example	Matches
`$eq`	`{"environment": {"$eq": "prod"}}`	Exact tag value
`$in`	`{"region": {"$in": ["us-east-1", "us-west-2"]}}`	Any listed tag value
`$contains`	`{"owner": {"$contains": "agent"}}`	Tag value contains literal text
`$starts_with`	`{"region": {"$starts_with": "us-"}}`	Tag value starts with literal text
`$ends_with`	`{"owner": {"$ends_with": "@platform"}}`	Tag value ends with literal text
`$exists`	`{"archived": {"$exists": False}}`	Tag key presence or absence

$exists checks only whether the tag key is present, regardless of its value. To match a specific value, use an exact match instead.

await mesa.repos.list(
    tags={
        "archived": {"$exists": False},
        "lifecycle": {"$eq": "active"},
    }
)

Complex Composition

This example selects active production-like skill or memory repos that are owned by platform teams and located in US regions:

result = await mesa.repos.list(
    tags={
        "$and": [
            {"environment": {"$in": ["prod", "staging"]}},
            {"region": {"$starts_with": "us-"}},
            {
                "$or": [
                    {"kind": "skill", "owner": {"$contains": "agent"}},
                    {"kind": "memory", "owner": {"$ends_with": "@platform"}},
                ]
            },
            {"$not": {"lifecycle": "archived"}},
            {"archived": {"$exists": False}},
        ]
    }
)

Matching semantics:

Everything is case-insensitive: operator names, tag keys (normalized to lowercase), and tag value comparisons.
$and matches when all child filters match, $or when any child matches, and $not negates its child filter.
$contains, $starts_with, and $ends_with match literal text — %, _, and \ in the search text are escaped, not treated as wildcards.
Filters are limited to depth 8, 64 total clauses, 32 items in $and, $or, and $in arrays, and 256 characters per tag key or value.

The Python SDK serializes filter dictionaries and sends them to the API. Invalid filters return 400 INVALID_REQUEST from the server. For direct REST calls, pass the filter as a JSON-encoded string in the tags query parameter:

import json
from urllib.parse import quote

tags = json.dumps({"$and": [{"environment": "prod"}, {"$not": {"lifecycle": "archived"}}]})
url = f"/v1/acme/repos?tags={quote(tags, safe='')}"

Legacy comma-separated string filters ("environment:prod,team:core") are still accepted but deprecated. Pass the listed repo names into fs.mount() to mount the filtered set of repositories:

result = await mesa.repos.list(tags={"$and": [{"environment": "prod"}, {"kind": "skill"}]})

async with mesa.fs.mount(
    repos=[repo.name for repo in result.repos],
    authors=[{"name": "Workspace Agent", "email": "agent@example.com"}],
) as fs:
    ...

Response

str | None

Cursor for the next page, or null when no more results remain.

bool

Whether another page of results is available.

list[Repo]

Repository objects.

Repo

str

Repository ID.

str

Organization slug.

str

Repository name.

str

Default bookmark name.

str

Current change ID at the default bookmark tip.

UpstreamConfig | None

Configured upstream remote, or null when no upstream is configured.

datetime

Creation time.

dict[str, str]

Repository tags.

UpstreamConfig

str

Upstream Git remote URL.

'token' | 'username_password' | None

Stored upstream authentication kind, or null when the upstream is public.

​Options

​Tag Filters

​Value Operators

​Complex Composition

​Response

​Repo

​UpstreamConfig

Options

Tag Filters

Value Operators

Complex Composition

Response

Repo

UpstreamConfig