canonical: https://jentic.com/apis/microcks.local/microcks # Microcks API v1.7 Microcks is the Kubernetes-native open-source tool for API and microservices mocking and contract testing. Its administrative API exposes endpoints to manage services and APIs, run import jobs against OpenAPI, AsyncAPI, and Postman artefacts, store secrets, and execute conformance tests with detailed test results. The 44-endpoint REST API is protected by Keycloak-issued JWTs and supports import, export, and snapshot workflows for CI integration. ## For AI agents Manage mocked services, run import jobs, kick off contract tests, and inspect Microcks test results so agents can drive an internal mocking and testing platform. ## Scope Does not generate API specs, host production traffic, or perform performance or security testing - use for mocking, contract testing, and import lifecycle management only. ## Capabilities - List, retrieve, and delete services and APIs registered in Microcks - Create, schedule, activate, start, and stop import jobs that ingest API artefacts - Upload artefacts directly via `/artifact/upload` for one-off imports - Trigger new contract tests, retrieve TestResults, and read messages or events for individual TestCases - Manage secrets used by import jobs to fetch private artefacts - Override service operations and update service metadata or labels - Import and export Microcks snapshots for environment promotion ## Use cases ### Continuous Mock Refresh from Source Repos Platform teams configure Microcks ImportJobs that periodically pull OpenAPI or AsyncAPI artefacts from a Git repository so that mocks always match the latest contract. The /jobs endpoints create and schedule the job, `/jobs/{id}/start` runs it on demand, and `/artifact/upload` covers the case where an artefact is staged from CI rather than pulled. Example prompt: Create an ImportJob via POST /jobs pointing at the OpenAPI artefact URL, then PUT `/jobs/{id}/start` to run it immediately. ### Contract Testing in CI Pipelines QA and platform teams trigger Microcks tests from CI by calling POST /tests with a target service, version, and runner type, then poll GET `/tests/{id}` for results and use `/tests/{id}/messages/{testCaseId}` to retrieve the request/response samples for any failures. This produces evidence-rich contract test runs without leaving the pipeline. Example prompt: Submit POST /tests for service ID 'svc_42' against the staging endpoint, poll GET `/tests/{id}` until completion, and return any failed TestCases. ### Snapshot Promotion Across Environments Teams promoting mock and test definitions across environments use POST /import and GET /export to move a Microcks snapshot from staging to production. Combined with /secrets management, the same import-export workflow works for environments that pull artefacts from private locations. Example prompt: Call GET /export to capture the staging snapshot, then POST /import in production with the same payload. ### Agent-Operated Mock Platform An AI agent on a developer experience team can drive Microcks through Jentic - refreshing mocks after a contract change, kicking off tests, and surfacing failures in chat. The agent searches by intent, loads the right schema for /jobs, /tests, or /services, and executes with the JWT handled inside your Jentic One instance. Example prompt: Search Jentic for 'run a contract test in Microcks', load POST /tests, and submit a test for the most recently imported service. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/services` | List Services and APIs registered in Microcks | | POST | `/jobs` | Create an ImportJob | | PUT | `/jobs/{id}/start` | Start an ImportJob immediately | | POST | `/tests` | Trigger a new contract test | | GET | `/tests/{id}` | Retrieve a TestResult | | POST | `/artifact/upload` | Upload an artefact directly | | POST | `/import` | Import a Microcks snapshot | | GET | `/export` | Export a Microcks snapshot | ## Key resources - **Services** — List, retrieve, delete, and search services and APIs registered in Microcks - **Jobs** — Create, schedule, activate, start, and stop import jobs that ingest artefacts - **Tests** — Trigger contract tests and read TestResults, messages, and events per TestCase - **Secrets** — CRUD for secrets used during artefact imports - **Resources** — Read raw resources attached to a service - **Snapshot** — Export and import Microcks snapshots for environment promotion ## Why Jentic - **Setup:** Wiring Microcks by hand means running the Keycloak OAuth 2.0 flow for its jwt-bearer scheme, pointing at your own Microcks host, and setting the Authorization header yourself. Through Jentic you install once, import Microcks from the API Directory, store the client credentials once, and your agent calls it. - **Permission scoping:** Microcks puts jobs and tests by id in the URL path (`/jobs/{id}/start`, `/tests/{id}`), so a rule can pin your agent to specific resources. You choose the operations it may call, so starting import jobs or triggering an export is not included unless you add it. - **Credential handling:** Your Microcks Keycloak credentials and issued JWTs are stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'run a contract test' or 'create an import job', and Jentic returns the matching Microcks operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **WireMock** — Java-based API mock server with a similar admin API - **SwaggerHub** — Hosted OpenAPI design and registry - **GitHub** — Source repository hosting OpenAPI artefacts ## FAQ ### What authentication does the Microcks API use? Microcks accepts OAuth 2.0 JWT tokens issued by its bundled Keycloak instance, configured via the GET `/keycloak/config` endpoint. Through Jentic the JWT is stored in the encrypted vault and added to the Authorization header at execution time. ### Can I import a Postman collection as a service? Yes - POST `/artifact/upload` accepts Postman collections alongside OpenAPI and AsyncAPI artefacts. For repeatable imports use POST /jobs with the artefact URL so Microcks pulls and refreshes it on a schedule. ### What are the rate limits for the Microcks API? Microcks itself does not enforce documented per-endpoint rate limits - limits are governed by the deployment topology and the Keycloak token policy. For high-frequency CI integrations, batch service queries through `/services/search` and reuse tokens. ### How do I trigger a contract test through Jentic? Search Jentic for 'run a Microcks test', load POST /tests, and submit the service ID, target endpoint, and runner type. Jentic adds the JWT from your stored credential and the agent polls GET `/tests/{id}` for completion. ### Is Microcks free to use? Yes - Microcks is open-source under Apache 2.0 and you self-host it. The API is part of the open-source distribution; commercial support is available from the Microcks team but is not required to use the API. ### Can I override individual mock operations without re-importing? Yes - PUT `/services/{id}/operation` lets you tweak a single operation's settings, and PUT `/services/{id}/metadata` updates labels and metadata without re-running the import job. ### Can I limit what my agent is allowed to do with the Microcks API? Yes. Because you self-host Jentic One, your own rules decide which Microcks operations the agent may call, so you can allow read-only calls like GET /services and GET `/tests/{id}` while withholding write actions such as POST /jobs, PUT `/jobs/{id}/start`, POST /tests, or POST /import. Since Microcks addresses jobs and tests by id in the URL path (`/jobs/{id}/start`, `/tests/{id}`), you can also pin the agent to specific resources rather than the whole platform. Nothing that starts an import job or triggers an export runs unless you have granted that operation.