a/apiwerk
User guide

Your first API in apiwerk

From your source contract to a documentation URL. Start with a simple portal, then add editing, guides, and team review.

Sign in and organization

  1. Open the workspace. On a self-hosted server, register on the sign-in page (if enabled by the administrator), verify your email, and sign in. Check spam or contact the server administrator if the email is missing. The Sites demo uses ChatGPT sign-in.
  2. Your personal organization is created at first sign-in. Select it at the top of the workspace; create a separate organization for another project. APIs, members, and publications belong to the selected organization.

apiwerk hosts documentation, not your API server. OpenAPI servers URLs should point to the working API you operate separately.

Import an API

  1. In the API catalog, choose Import API. For an existing OpenAPI document, upload .json, .yaml, or .yml, or paste source. For Postman or Insomnia, first select the Collection tab and follow the conversion steps below. You can select the demo contract to explore.
  2. Supported: OpenAPI 3.0 and 3.1; 3.2 support is experimental. One UTF-8 file up to 5 MiB. Provide info.title, info.version, and a paths object. External $refs are not fetched: bundle the contract into one file with local references first.
  3. Set a name and slug, or derive them from info.title during validation. The version comes from info.version. Russian names are supported and slugs are transliterated automatically. Validate and import.

After import, open the API card. The validated OpenAPI document is saved as an immutable revision; collection conversion saves the generated OpenAPI, not the original collection. Global import creates a separate API. To update an existing API, use Fix in editor. Published documentation is not overwritten.

Postman and Insomnia

You can start from an HTTP collection: Postman Collection 2.0 or 2.1 JSON, Insomnia export v4 JSON (legacy), or an Insomnia v5 YAML collection. Conversion produces an editable OpenAPI draft: a starting point for documentation, not a complete contract or a test runner.

  1. Open Import API and select Collection. Upload one UTF-8 .json, .yaml, or .yml file, or paste its contents. Both the input and generated OpenAPI must be at most 5 MiB each.
  2. Select Convert collection. Review imported operation counts, skips, and warnings. Conversion runs in your browser: it sends no collection requests, runs no scripts or environments, and reads no referenced local files.
  3. Review and edit the generated OpenAPI source. Check the server URL, methods, paths, parameters, authentication, bodies, and responses. Schemas inferred from examples are approximate: verify required fields, types, and response codes yourself. Literal parameter, header, body, and response-example values are omitted.
  4. Then validate and import normally. Only the OpenAPI document submitted for validation goes to the server, not the original collection. A new API remains private until a separate publication step. Open the editor, resolve quality errors, check the private preview, and publish using the steps below.

Skipped content is not completed documentation: GraphQL, WebSocket, gRPC, executable templates, tests, and file attachments do not become a complete HTTP contract. Unresolved variables and ambiguous operations need review. Omitting values does not guarantee removal of every secret: names, descriptions, URLs, and paths can still contain private data. Review them before importing and publishing.

The Collection tab is available when creating a new API. To update an existing API, convert locally, copy the generated OpenAPI into its editor, and follow the normal draft workflow; another global import would create a separate API.

Editor and formats

The editor provides JSON/YAML source and visual editing of documentation fields: titles, descriptions, and tags. Edit contract structure in source. Save your draft and run checks before creating a revision.

Descriptions can import UTF-8 .md, .markdown or .txt files (up to 20,000 characters) and export .md. They support safe Markdown: headings, lists, links, quotes, code blocks, and GFM tables. Arbitrary HTML, executable MDX, and scripts do not execute. Your API content is not automatically translated when switching interface language.

The portal displays schemas, parameters, responses, and multiple media types: JSON, XML, text, forms, and multipart. Code samples are available for cURL, JavaScript, and Python. This is a contract projection, not a guarantee that every OpenAPI extension is supported.

First publication

  1. Open API management, review quality checks, and resolve blocking errors. Revision comparison helps identify breaking changes.
  2. A preview is created automatically after import or saving a revision if the contract passes the required checks. Check its reference, search, schemas, and source download. Preview is restricted to organization members.
  3. Choose Publish: this activates public documentation. Copy the URL from Portals and test it in a private browser window without signing in.

A new API uses direct publication by default: its owner can publish OpenAPI-only documentation after quality checks. If independent review is enabled, another eligible member must approve. Publishing does not expose drafts, private previews, or internal discussions. Never put real keys, passwords, or personal data in contract examples.

Markdown and team releases

A release containing standalone guides needs a second member with publishing permission. Authors cannot approve their own artifacts. Invite a reviewer before starting.

  1. In Content, select an API, create a guide, and save its Markdown. The editor shows source and a safe preview.
  2. First save the intended OpenAPI revision and set page order in Content. In API management, open Release candidates and set a name and portal language. The candidate pins the current saved main and the complete current guide set in its existing order. Language selection does not translate the content.
  3. Build an artifact and request review. Another owner, admin, or publisher who did not contribute to the artifact checks and approves that exact build. Create and check its private preview. Refresh the Quality Gate in the production release section, then activate the exact artifact after the check succeeds.

Changing release contents requires a new build and approval. Publishing an ordinary OpenAPI preview does not automatically include standalone guides.

Access and team

An owner or admin invites a member by email in Team and shares the generated link. Invitation emails are not sent automatically yet. The recipient must sign in with that verified email address and accept the invitation. Reopen the invitation link after signing in if necessary.

  • Owner and admin: organization and member management within their role.
  • Author: APIs and drafts. Publisher: review and publication. Viewer: read accessible materials.

Private APIs are member-only. Published public portals are available without sign-in; visibility and publication status are checked on each read.

Updates and recovery

Open the existing API in its editor, save and validate changes, then create a revision and preview. The published version remains unchanged while you work. Deployment history offers eligible previous versions for rollback. Deactivation hides production; archiving an API is a separate confirmed action with retention rules.

On a conflict, reload current data and review your changes again. If delivery is unconfirmed, retry the same attempt using the UI instead of blindly creating a new release. Save your draft before leaving, or download a local recovery copy when offered.

Early-access limitations

This is an early platform release, not the complete commercial specification. Not yet available:

  • Multi-file imports and standalone AsyncAPI, GraphQL, or Protobuf formats. Postman and Insomnia are available only through limited HTTP-collection conversion to OpenAPI, without running requests or tests.
  • Executable MDX, a full structural visual designer, and automatic documentation translation.
  • Real Try it requests, API proxying, consumer key issuance, billing, and API usage analytics.
  • Self-service custom domains for individual portals. VPS installations use one installation domain and /docs/… paths.

If an action is unavailable, check the selected organization, your role, and whether the previous step is complete. Contact the administrator of your installation about registration, email, quotas, or data recovery.

Open your workspace