API Operations · In design

Operational controls
for your API.

OpenAPI says what your endpoints do.
DNA says who may call them, and what gets recorded. Paste your spec. The reading runs in your browser.

Join the waitlist

Northwind Payments APIOAS 3.0Demo model

The document being read26 operations · 3 KB

{
  "openapi": "3.0.3",
  "info": {
    "title": "Northwind Payments API",
    "version": "2026-04-01"
  },
  "paths": {
    "/v1/customers": {
      "get": {
        "operationId": "listCustomers",
        "summary": "List customers"
      },
      "post": {
        "operationId": "createCustomer",
        "summary": "Create a customer"
      }
    },
    "/v1/customers/{id}": {
      "get": {
        "operationId": "getCustomer",
        "summary": "Retrieve a customer"
      },
      "patch": {
        "operationId": "updateCustomer",
        "summary": "Update a customer"
      },
      "delete": {
        "operationId": "deleteCustomer",
        "summary": "Delete a customer"
      }
    },
    "/v1/customers/{id}/payment-methods": {
      "get": {
        "operationId": "listPaymentMethods",
        "summary": "List a customer’s payment methods"
      },
      "post": {
        "operationId": "addPaymentMethod",
        "summary": "Attach a payment method"
      }
    },
    "/v1/payments": {
      "get": {
        "operationId": "listPayments",
        "summary": "List payments"
      },
      "post": {
        "operationId": "createPayment",
        "summary": "Create a payment"
      }
    },
    "/v1/payments/{id}": {
      "get": {
        "operationId": "getPayment",
        "summary": "Retrieve a payment"
      }
    },
    "/v1/payments/{id}/capture": {
      "post": {
        "operationId": "capturePayment",
        "summary": "Capture an authorised payment"
      }
    },
    "/v1/payments/{id}/refund": {
      "post": {
        "operationId": "refundPayment",
        "summary": "Refund a payment"
      }
    },
    "/v1/payments/{id}/void": {
      "post": {
        "operationId": "voidPayment",
        "summary": "Void a payment"
      }
    },
    "/v1/invoices": {
      "get": {
        "operationId": "listInvoices",
        "summary": "List invoices"
      },
      "post": {
        "operationId": "createInvoice",
        "summary": "Draft an invoice"
      }
    },
    "/v1/invoices/{id}": {
      "get": {
        "operationId": "getInvoice",
        "summary": "Retrieve an invoice"
      },
      "patch": {
        "operationId": "updateInvoice",
        "summary": "Update a draft invoice"
      }
    },
    "/v1/invoices/{id}/pay": {
      "post": {
        "operationId": "payInvoice",
        "summary": "Pay an invoice"
      }
    },
    "/v1/invoices/{id}/send": {
      "post": {
        "operationId": "sendInvoice",
        "summary": "Email an invoice"
      }
    },
    "/v1/payouts": {
      "get": {
        "operationId": "listPayouts",
        "summary": "List payouts"
      },
      "post": {
        "operationId": "createPayout",
        "summary": "Create a payout"
      }
    },
    "/v1/payouts/{id}": {
      "get": {
        "operationId": "getPayout",
        "summary": "Retrieve a payout"
      }
    },
    "/v1/disputes": {
      "get": {
        "operationId": "listDisputes",
        "summary": "List disputes"
      }
    },
    "/v1/disputes/{id}": {
      "get": {
        "operationId": "getDispute",
        "summary": "Retrieve a dispute"
      }
    },
    "/v1/disputes/{id}/evidence": {
      "post": {
        "operationId": "submitEvidence",
        "summary": "Submit dispute evidence"
      }
    },
    "/v1/reports/latest": {
      "get": {
        "summary": "The most recent settlement report"
      }
    }
  }
}

22 of 26 endpoints are governed. 4 gaps.

Payment 6 2 gaps

GET /v1/payments Payment Access

Operation: Payment.List
Rule: Payment Access
Required: Support.Agent, Finance.Admin
Scope: Organization
Audit: On write

POST /v1/payments Payment Authority

Operation: Payment.Create
Rule: Payment Authority
Required: Finance.Admin, Finance.Manager
Scope: Organization
Feature: payments_v2
Audit: Required

GET /v1/payments/{id} Payment Access

Operation: Payment.Read
Rule: Payment Access
Required: Support.Agent, Finance.Admin
Scope: Organization
Audit: On write

POST /v1/payments/{id}/capture Payment Authority

Operation: Payment.Capture
Rule: Payment Authority
Required: Finance.Admin, Finance.Manager
Scope: Organization
Feature: payments_v2
Audit: Required

POST /v1/payments/{id}/refund nothing governs this

Operation: Payment.Refund
Rule: none
Required: nobody — any caller the edge authenticates
Scope: unbounded
Audit: nothing is recorded

Not a weaker rule — no rule. Nobody decided this one was safe to leave open; it was never considered, and nothing in the stack was in a position to notice.

POST /v1/payments/{id}/void nothing governs this

Operation: Payment.Void
Rule: none
Required: nobody — any caller the edge authenticates
Scope: unbounded
Audit: nothing is recorded

Not a weaker rule — no rule. Nobody decided this one was safe to leave open; it was never considered, and nothing in the stack was in a position to notice.

Payout 3 1 gap

GET /v1/payouts Treasury Access

Operation: Payout.List
Rule: Treasury Access
Required: Finance.Admin
Scope: Organization
Audit: Required

POST /v1/payouts nothing governs this

Operation: Payout.Create
Rule: none
Required: nobody — any caller the edge authenticates
Scope: unbounded
Audit: nothing is recorded

Not a weaker rule — no rule. Nobody decided this one was safe to leave open; it was never considered, and nothing in the stack was in a position to notice.

GET /v1/payouts/{id} Treasury Access

Operation: Payout.Read
Rule: Treasury Access
Required: Finance.Admin
Scope: Organization
Audit: Required

Customer 5

GET /v1/customers Customer Access

Operation: Customer.List
Rule: Customer Access
Required: Support.Agent, Finance.Admin
Scope: Organization
Audit: On write

POST /v1/customers Customer Administration

Operation: Customer.Create
Rule: Customer Administration
Required: Finance.Admin
Scope: Organization
Audit: Required

GET /v1/customers/{id} Customer Access

Operation: Customer.Read
Rule: Customer Access
Required: Support.Agent, Finance.Admin
Scope: Organization
Audit: On write

DELETE /v1/customers/{id} Customer Administration

Operation: Customer.Delete
Rule: Customer Administration
Required: Finance.Admin
Scope: Organization
Audit: Required

PATCH /v1/customers/{id} Customer Administration

Operation: Customer.Update
Rule: Customer Administration
Required: Finance.Admin
Scope: Organization
Audit: Required

PaymentMethod 2

GET /v1/customers/{id}/payment-methods Customer Access

Operation: PaymentMethod.List
Rule: Customer Access
Required: Support.Agent, Finance.Admin
Scope: Organization
Audit: On write

POST /v1/customers/{id}/payment-methods Customer Administration

Operation: PaymentMethod.Create
Rule: Customer Administration
Required: Finance.Admin
Scope: Organization
Audit: Required

Invoice 6

GET /v1/invoices Billing Access

Operation: Invoice.List
Rule: Billing Access
Required: Finance.Admin, Billing.Clerk
Scope: Organization
Audit: On write

POST /v1/invoices Billing Authority

Operation: Invoice.Create
Rule: Billing Authority
Required: Finance.Admin
Scope: Organization
Audit: Required

GET /v1/invoices/{id} Billing Access

Operation: Invoice.Read
Rule: Billing Access
Required: Finance.Admin, Billing.Clerk
Scope: Organization
Audit: On write

PATCH /v1/invoices/{id} Billing Authority

Operation: Invoice.Update
Rule: Billing Authority
Required: Finance.Admin
Scope: Organization
Audit: Required

POST /v1/invoices/{id}/pay Payment Authority

Operation: Invoice.Pay
Rule: Payment Authority
Required: Finance.Admin, Finance.Manager
Scope: Organization
Feature: payments_v2
Audit: Required

POST /v1/invoices/{id}/send Billing Authority

Operation: Invoice.Send
Rule: Billing Authority
Required: Finance.Admin
Scope: Organization
Audit: Required

Dispute 3

GET /v1/disputes Dispute Handling

Operation: Dispute.List
Rule: Dispute Handling
Required: Support.Lead, Finance.Admin
Scope: Organization
Audit: Required

GET /v1/disputes/{id} Dispute Handling

Operation: Dispute.Read
Rule: Dispute Handling
Required: Support.Lead, Finance.Admin
Scope: Organization
Audit: Required

POST /v1/disputes/{id}/evidence Dispute Handling

Operation: Dispute.Evidence
Rule: Dispute Handling
Required: Support.Lead, Finance.Admin
Scope: Organization
Audit: Required

Unresolved 1

GET /v1/reports/latest resource or act?

Path: /v1/reports/latest
Why: resource or act?

The last segment could be a sub-resource or an act, and nothing in the document decides which.

x-dna:
  operation: resource.act

The finding

Most of it is governed.
Which parts aren’t?

Your document says exactly what POST /payments takes. It doesn’t say who may call it, or whether anyone will know they did.

Those answers exist — in a middleware, a decorator, someone’s head, four places that disagree. None are in the file your company treats as the API’s definition, so nothing you own can name the endpoints nothing covers.

OpenAPI describes your API. DNA describes your organization.

Northwind Payments APIOAS 3.0Demo model

22 of 26 endpoints are governed. 4 gaps.

POST/v1/payments/{id}/refundPayment.Refundnothing governs this

POST/v1/payments/{id}/voidPayment.Voidnothing governs this

POST/v1/payoutsPayout.Createnothing governs this

GET/v1/reports/latest—cannot be named

POST/v1/paymentsPayment.CreatePayment Authority

GET/v1/paymentsPayment.ListPayment Access

POST/v1/invoices/{id}/payInvoice.PayPayment Authority

Nobody wrote a rule for these three. They were not judged too risky to govern — they were never considered, and nothing in the stack was in a position to notice.

POST/v1/paymentsCreate a payment

Parameters

Request body

Responses

DNA

Operation: Payment.Create
Resource: Payment
Required: Finance.Admin
Scope: Organization
Feature: payments_v2
Audit: Required

Where the convention breaks

/orders.fulfill:
  post:
    x-dna:
      operation: order.fulfill
      target: $.body.orderId

The bind

Parameters. Responses.
Authority.

A third section on an endpoint you already document — not chrome painted over Swagger. It is read from the document you already publish: across nine large public APIs,88% of operations resolve from the path alone.

The rest take five lines of x-dna, which Swagger ignores by design.operation names the act, target names what it acts on. Your model knows the rest.

Nothing binds itself. A machine may observe; a person decides.

The edge

One rule. Three answers.

One middleware resolves the endpoint to its operation, resolves the target from the request, and asks the same evaluator a button in your app asks. Refusal happens before your handler.

app.use(dnaGuard({ openapi: './openapi.json' }));

No parameter names who is asking — a caller that could describe its own actor could authorize itself. The actor comes from the credential you already authenticated.

We are not a gateway. Nothing proxies your traffic or terminates your TLS. Your edge asks a question; fail-open or fail-closed is your call.

POST/v1/payments/{id}/refund

RuleRefund Authority — Finance, up to $5,000

Server response

200Dana Ruiz · Finance.Adminwithin her delegated limit

{ "refund": "re_8f2c", "amount": 240.00 }

403Sam Okafor · Support.Agentrefused before the handler ran

{ "error": "no grant for Payment.Refund" }

202Dana Ruiz · Finance.Admin$18,400 — over limit

{ "status": "escalated", "to": "CFO" }

And the record

Payment.Refund · Dana Ruiz · Finance.Admin
under Refund Authority · audit 83f91c4e

A person and the authority they used — not an API key.

POST/v1/payments/{id}/refundTry it out

Parameters

idpay_4c81

DNA

acting as Dana Ruiz · Finance.Admin

AuthorizationPayment.Refund

ScopeNorthwind Ltd

Featurerefunds_v2

Limit$240.00 of $5,000

Switch the actor to Support.Agent and there is no button to press.

The explorer

Swagger documents.
DNA operates.

Keep Swagger UI. We do not render into it and we do not replace it — we read the same document it reads.

Documentation asks what does this endpoint take. An operational console asksmay I, as me, right now — and answers before you press, not with a status code afterwards.

The smallest version is one link in the Swagger page you already have:View in DNA →. It costs a day, and it tells us whether anyone wants the panel.

FAQ

Do I have to change my OpenAPI document?

Usually barely. Run the reader over nine large public APIs and 88% of operations resolve to a resource and an act from the path alone — Asana and Adyen resolve completely, Stripe at 97%, GitHub at 86%. The exception is an RPC-shaped API: Slack’s Web API resolves at 45%, because /chat.postEphemeral is a call rather than a resource. Those are exactly the endpoints x-dna exists for, and it is two lines each.

Is this a gateway? Do you sit in my request path?

No. Nothing proxies your traffic, terminates your TLS, or adds a box between your customers and your API. A middleware at your edge asks for a decision and acts on it, which is the same thing @dna/guard does behind a React control today. Whether an unanswered question fails open or fails closed is your call, made explicitly rather than defaulted quietly.

Are you replacing Swagger UI?

No, and we do not render anything into it either. Swagger UI documents your API and does it well. DNA reads the same document and answers a different question — may this actor call this, right now — which no documentation tool has ever been asked. The smallest useful integration is one View in DNA → link in the Swagger page you already have.

What does the number on this page actually measure?

Three things, deliberately kept apart. Naming comes from your OpenAPI document. Authentication comes from its security blocks — real, and worth reporting, but a token proves who you are, not that you may. Governance comes from your model, so a pasted spec gets no governance number from us; put a control on an endpoint yourself and the panel becomes a gap report on your own API. A page that blurred those three would be caught by the first person who looked.

How is it priced?

There is no new meter and no new tier. The API surface is included in every paid plan for the same reason the Overlay is — it is a surface on your model, not a product beside it, and we charge for authority rather than for looking. See the ladder →

Is this ready for production?

It is in design, which is a weaker claim than Agent Operations’ in build, and deliberately so. What works today is what is on this page: the reader is real and runs in your browser on your own document. The publish step, the middleware and the explorer are designed and not yet built, in that order. We are setting up a small number of design partners by hand and telling each of them exactly which half they are getting.

Run it on the spec you already publish.

Bring the API you would least like to explain to an auditor. The interesting part is never the endpoints we cannot name — it is the ones we can.

We are looking for design partners with an API older than the rules that govern it.

Operational controlsfor your API.

Most of it is governed.Which parts aren’t?

Parameters. Responses.Authority.

One rule. Three answers.

Swagger documents.DNA operates.

FAQ

Do I have to change my OpenAPI document?

Is this a gateway? Do you sit in my request path?

Are you replacing Swagger UI?

What does the number on this page actually measure?

How is it priced?

Is this ready for production?

Run it on the spec you already publish.

Operational controls
for your API.

Most of it is governed.
Which parts aren’t?

Parameters. Responses.
Authority.

Swagger documents.
DNA operates.