Integrators

This section is for developers connecting Mockomat workflows into broader engineering systems. Whether you are building a frontend that consumes a Mockomat mock API, automating model validation in CI/CD, or integrating Mockomat into your team's development pipeline, this page covers the patterns and practices you need.

API Endpoints Overview

Mockomat exposes two distinct API surfaces:

API	Endpoint	Purpose	Authentication
Management API	GET /graphql	Project CRUD, model configuration, user management	JWT (session-based)
Mock Runtime API	POST /mock/{slug}/graphql	Query mock data, test domain behavior	API key (Authorization: Bearer mck_…); guest projects: share token

The management API is used by the Mockomat web application and administrative tooling. The mock runtime API is what your applications consume as a mock backend.

Authentication

Every request to the mock runtime API of a project in your account carries an API key. Requests without a valid key are refused, whatever the project's preview share setting — a share link opens the preview page, not the API.

API Keys

Create keys in the app under Account → API keys, for the active project. API keys come with the Professional plan and above. Each key:

• Belongs to one project and answers only for that project
• Is shown in full once, when you create it — store it like a password
• Can carry an expiry date and can be revoked at any time
• Has a scope: Runtime queries mock data, Full also reaches the management API; a Management key cannot query the runtime

Send the key as a bearer token:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

The header X-API-Key: mck_your_api_key works as well.

Keep the key out of browser code

An API key is a secret. Call the mock API from server-side code, from CI, or through a dev-server proxy that adds the header (step 4 of the integration flow below) — never ship the key in a frontend bundle.

Guest Projects

A guest project (no account) has no API keys. Its endpoint answers to the project's share token — the token in its preview share link — passed as a query parameter:

curl -X POST "https://api.mockomat.com/mock/my-guest-project/graphql?token=<share-token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name } total } }"}'

Guest requests count against the guest session's daily request quota.

Actor Tokens (Optional)

Actor tokens tell the consumers of one API key apart, so that concurrent use of a key can be capped. They are optional — a request with only the API key is served.

1. Request a token with your API key:

curl -X POST https://api.mockomat.com/runtime/actors \
  -H "Authorization: Bearer mck_your_api_key"

Response:

{
  "actorToken": "act_abc123...",
  "expiresInSeconds": 900,
  "maxActors": 1,
  "currentActors": 1
}

2. Send it with your runtime requests:

curl -X POST https://api.mockomat.com/mock/my-project/graphql \
  -H "Authorization: Bearer mck_your_api_key" \
  -H "X-Actor-Token: act_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(page: 1, pageSize: 10) { items { id name price } total } }"}'

3. Idle expiry — a token expires after 15 minutes without requests; every request extends it. While all actor slots of a key are taken, a new actor gets 429 MAX_ACTIVE_ACTORS_REACHED with a Retry-After header.

int-01-authenticationMissing

Integration entry with auth and context setup.

Query Patterns

Basic List Query

query {
  products(page: 1, pageSize: 20) {
    items {
      id
      name
      price
      category {
        id
        name
      }
    }
    total
    page
    pageSize
  }
}

Detail Query

query {
  product(id: "abc-123") {
    id
    name
    price
    description
    category {
      id
      name
    }
  }
}

Filtered Query

The arguments are parameters the operation defines in API design (here minPrice on price with gte, category with eq); see Runtime for operators, search and pagination.

query {
  products(minPrice: 10, category: "electronics", pageSize: 50) {
    items {
      id
      name
      price
    }
    total
  }
}

Sorted and Paginated Query

query {
  products(sortField: "price", sortDirection: ASC, page: 2, pageSize: 20) {
    items {
      id
      name
      price
    }
    total
    page
    pageSize
  }
}

Nested Relation Query

query {
  customers(pageSize: 10) {
    items {
      id
      firstName
      lastName
      orders {
        id
        totalAmount
        createdAt
      }
    }
    total
  }
}

Recommended Integration Flow

1. Define a Stable Domain Scope

Before integrating, identify which entities and queries your application will consume. Do not integrate against a model that is still changing frequently — wait until the core structure is stable.

2. Lock Naming and Field Contracts

Treat the GraphQL schema as a contract. Once your application depends on specific query names and field structures, changes to those names will break the integration. Use the API design view in Mockomat to finalize query names before connecting consumers.

3. Validate Runtime Behavior

Run comprehensive queries through the runtime preview and verify:

• Field types match what your application expects
• Relation nesting works correctly
• Filters return the expected subsets
• Pagination produces clean page boundaries

4. Integrate Consumer Systems

Connect your test suite, backend-for-frontend, or other consumers to the mock endpoint. Keep the endpoint and the API key in configuration, so you can switch between Mockomat and your real backend.

A frontend app reaches the mock API through its dev-server proxy, which adds the key on the server side — so the key never ends up in the bundle:

// vite.config.ts — forwards /mock-api to Mockomat and adds the API key
export default defineConfig({
  server: {
    proxy: {
      '/mock-api': {
        target: 'https://api.mockomat.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/mock-api/, '/mock/my-project'),
        headers: { Authorization: `Bearer ${process.env.MOCKOMAT_API_KEY}` },
      },
    },
  },
});

// environment.ts — the app only knows the proxy path
export const environment = {
  apiUrl: '/mock-api/graphql',
  // Switch to real backend when ready:
  // apiUrl: 'https://api.myapp.com/graphql',
};

5. Promote to Export/Implementation

When the mock API contract is stable and your frontend is working correctly against it, use the Export feature to generate a production backend that implements the same contract.

int-02-ci-cd-flowMissing

CI/CD integration pattern with model and runtime gates.

CI/CD and Automation

Mockomat mock APIs can be integrated into your CI/CD pipeline to validate frontend behavior against a stable mock backend.

Pipeline Integration Patterns

Contract validation — run schema comparison checks when models change to detect breaking changes before they reach consumers.

Integration tests — point your integration test suite at the Mockomat endpoint to verify frontend behavior against realistic mock data.

Preview validation — before merging model changes, validate that the runtime produces expected results by querying the preview endpoint programmatically.

Example Pipeline Steps

# Example CI pipeline step
steps:
  - name: Run integration tests against mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: npm run test:integration

  - name: Smoke-check the mock API
    env:
      API_URL: https://api.mockomat.com/mock/my-project/graphql
      API_KEY: ${{ secrets.MOCKOMAT_API_KEY }}
    run: |
      # Fails the step on 401/403/404: a missing, revoked or wrong-project key
      curl -sf "$API_URL" \
        -H "Authorization: Bearer $API_KEY" \
        -H "Content-Type: application/json" \
        -d '{"query":"{ products(page: 1, pageSize: 1) { items { id } total } }"}'

Versioning Generated Artifacts

When using the export feature, version the generated backend code alongside your application:

• Commit generated code to a dedicated branch or repository.
• Tag exports with the model version or date.
• Include a changelog summarizing model changes since the last export.
• Review generated code diffs before merging into main.

Rate Limiting

Three limits apply to the mock runtime API:

Scope	Limit	When reached
Per IP address	60 requests per minute	429 TOO_MANY_REQUESTS — retry a minute later
Per account	The request quota of your plan (per day or per month)	429 TOO_MANY_REQUESTS until the quota resets
Per API key	Concurrent actors — only if you send actor tokens	429 MAX_ACTIVE_ACTORS_REACHED with a Retry-After header

Guest projects count against the guest session's daily quota.

Error Handling

A refused request answers with an HTTP error status and a JSON body. Branch on its code:

HTTP Status	Code	Meaning	Action
400	Bad Request	Invalid GraphQL, unknown or disabled operation, malformed body	Read message; fix the query or the operation name
401	UNAUTHENTICATED	No API key sent (guest project: missing or wrong share token)	Send Authorization: Bearer mck_…
401	API_KEY_INVALID	Unknown, revoked or deleted key	Create a new key
401	API_KEY_EXPIRED	The key's expiry date has passed	Create a new key
401	ACTOR_TOKEN_INVALID	Malformed X-Actor-Token	Request a token from /runtime/actors, or leave the header out
403	API_KEY_SCOPE_INSUFFICIENT	Management-only key	Use a Runtime or Full key
404	PROJECT_NOT_FOUND	Unknown slug, or a project the key does not belong to (on /runtime/actors: the key's project was deleted)	Check the slug; use a key of this project
429	TOO_MANY_REQUESTS	Per-IP rate limit or plan quota reached	Wait, then retry
429	MAX_ACTIVE_ACTORS_REACHED	All actor slots of the key are in use	Wait for Retry-After
429	RATE_LIMIT_EXCEEDED	Too many actor-token requests for one key (POST /runtime/actors)	Wait for Retry-After; reuse a token while it is active
503	QUERY_TIMEOUT	The query ran too long	Retry; narrow the query

Error Response Format

{
  "statusCode": 401,
  "code": "API_KEY_INVALID",
  "message": "API_KEY_INVALID",
  "path": "/mock/my-project/graphql",
  "timestamp": "2026-10-05T09:30:00.000Z"
}

A 429 with a Retry-After header also carries retryAfter (seconds) in the body. A served request answers 200 with a GraphQL body; data-level problems arrive in errors[] — for example, extensions.code NOT_READY means the table is not mapped to data yet.

Observability and Diagnostics

Track these core signals across environments to maintain integration reliability:

Key Metrics

• Query stability — are responses consistently structured? Watch for unexpected schema changes.
• Response shape drift — are field types or nesting levels changing between model updates?
• Relation lookup reliability — do nested queries consistently resolve correctly?
• Error and timeout patterns — are certain queries consistently slow or failing?
• Rate limit proximity — how close are you to hitting request or concurrency limits?

Monitoring Recommendations

• Log all API responses (or at least status codes and response times) in your consumer application.
• Set up alerts for HTTP 429 and 401 responses — these indicate configuration or capacity issues.
• Compare response schemas periodically against a baseline to detect unintended drift.
• Monitor actor token refresh patterns to optimize your concurrency strategy.

int-03-observabilityMissing

Observability checkpoints for integration reliability.

Best practice

Developer / Integrator

Treat Mockomat artifacts as contract-first assets. Keep model intent, runtime behavior, and implementation decisions traceable in the same change set. When your frontend depends on a specific query shape, document that dependency and validate it in CI.

Enterprise integration note

Enterprise User

For enterprise environments, use separate API keys per environment (development, staging, production). This lets you track usage per environment and rotate keys independently. Combine with actor tokens to control exactly how many concurrent consumers each environment supports.