Entity Search (name → ID picker)

Mockarty exposes a unified entity picker endpoint that resolves a
human-readable name into the canonical UUID across every major resource
type. The UI pickers (Test Plan item builder, schedule builder, webhook
builder, merge Test Runs, DAG editor) all call this endpoint — the API,
CLI, SDKs, and MCP tool expose the exact same surface so scripts and
AI agents see the same data a human does in the UI.

About URLs in examples: all examples use http://localhost:5770.
Replace with your Mockarty address if your instance lives elsewhere. See
Tips & Useful Features.

Related pages: CLI User Guide ·
SDK Guide · API Reference

When to use it

• CI/CD pipelines — resolve a Test Plan name into an ID before
  triggering a run.
• Cross-entity lookup — find everything in a namespace called
  checkout in a single call.
• Agent workflows — MCP agents call search_entities first to turn
  a human-friendly phrase into the IDs other tools need.

Supported types

mock, test_plan, perf_config, fuzz_config, chaos_experiment,
contract_pact, request, collection, ui_test, wiki_page,
whiteboard, test_case, issue, user.

request and collection are API Tester entities — useful when building
Test Plans that include functional HTTP steps. ui_test surfaces saved UI
recordings so a Test Plan item can reference them directly. wiki_page
matches page titles and body text; whiteboard matches board name and
description. test_case finds TCM test cases by name or description and
returns the short case number alongside the id. issue finds tracker
issues by title or key (for example MK-12); private-project issues stay
visible only to their members. user resolves members of the current
namespace by login (or member as an alias) and returns the login with the
user id — it powers the “Deleted by” suggestions on the Recycle Bin page and
never returns e-mail addresses.

Endpoint

Query parameters:

Response:

{
  "items": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "type": "test_plan",
      "name": "smoke-suite",
      "namespace": "production",
      "createdAt": "2026-04-19T12:00:00Z",
      "numericId": 42
    }
  ],
  "total": 1
}

numericId is only present for entities that carry a stable numeric ID
(Test Plans today). items is always a non-nil array.
For test_plan, total counts all matching active plans in the selected
namespace, even when the first page contains fewer rows than the catalogue.
Advance offset until you have read total rows. A literal % or _ in
q is searched as text, not as a wildcard.

Authentication

Pass an API token via X-API-Key. Tokens are issued in Settings → API
Tokens (or POST /api/v1/auth/tokens). Tenant-scoped tokens silently ignore
?namespace= — the namespace bound to the token wins.

export MOCKARTY_URL=http://localhost:5770
export MOCKARTY_API_TOKEN=mk_7_...
export MOCKARTY_NAMESPACE=default

Find all test plans containing “smoke”

cURL

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/entity-search?type=test_plan&q=smoke&limit=25"

CLI

mockarty-cli search test_plan --query smoke --limit 25

Go

resp, err := client.EntitySearch().Search(ctx, mockarty.EntitySearchRequest{
    Type:  mockarty.EntityTypeTestPlan,
    Query: "smoke",
    Limit: 25,
})
for _, it := range resp.Items {
    fmt.Printf("%s  %s\n", it.ID, it.Name)
}

Python

resp = client.entity_search.search(
    entity_type="test_plan",
    query="smoke",
    limit=25,
)
for item in resp.items:
    print(item.id, item.name)

Java

EntitySearchResponse resp = client.entitySearch().search(
    new EntitySearchRequest()
        .type(EntitySearchRequest.TYPE_TEST_PLAN)
        .query("smoke")
        .limit(25));
for (EntitySearchResult item : resp.getItems()) {
    System.out.println(item.getId() + "  " + item.getName());
}

Paginate mocks in the active namespace

For mock search, total counts every matching mock within the searchable
catalogue, including matches beyond the first page. A catalogue above 10,000
mocks returns an error instead of an incomplete result. For a global search,
select one namespace; for a larger single namespace, use the dedicated mock
listing API.

cURL

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/entity-search?type=mock&limit=50&offset=0"

curl -s -H "X-API-Key: $MOCKARTY_API_TOKEN" \
  "$MOCKARTY_URL/api/v1/entity-search?type=mock&limit=50&offset=50"

CLI

mockarty-cli search mock --limit 50 --offset 0
mockarty-cli search mock --limit 50 --offset 50

Go

for offset := 0; ; offset += 50 {
    resp, err := client.EntitySearch().Search(ctx, mockarty.EntitySearchRequest{
        Type:   mockarty.EntityTypeMock,
        Limit:  50,
        Offset: offset,
    })
    if err != nil || len(resp.Items) == 0 {
        break
    }
    // ... process resp.Items
}

JSON output from the CLI

The CLI respects the global --output json flag so it can be piped into
jq inside a CI pipeline:

mockarty-cli --output json search test_plan --query smoke \
  | jq -r '.items[] | [.id, .name] | @tsv'

Use it from an AI agent (MCP)

Agents talk to Mockarty’s built-in MCP server. Call the search_entities
tool before issuing tools that require an ID:

{
  "name": "search_entities",
  "arguments": {
    "type": "test_plan",
    "q": "smoke",
    "limit": 25
  }
}

The agent receives the same { "items": [...], "total": N } envelope and
can then feed items[].id into run_test_plan, get_test_plan, etc.

Errors

The CLI, SDKs, and MCP tool all raise the same error codes before any
HTTP traffic is sent — a typo in the type name fails fast client-side.