[Service name] API

Owner: [Team and contact]
Version: [Version]
Status: Draft
Base URL: https://api.example.com/v1

The endpoints and payloads below are examples. Replace them with the actual API contract; never include live credentials.

Overview

[Describe the API’s purpose, intended consumers, and resource model.]

Authentication and authorization

Authorization: Bearer <access-token>

• Obtain a token: [Authentication flow or documentation link.]
• Required permissions: [Scopes or roles per operation.]
• Resource access: [Ownership and tenant checks.]
• Expiry and renewal: [Token lifecycle.]

Endpoints

Method	Path	Purpose	Permission
GET	/documents	List accessible documents	[Read scope]
POST	/documents	Create a document	[Write scope]
GET	/documents/{id}	Retrieve one document	[Read scope]

Create a document

POST /documents

Field	Type	Required	Constraints
title	string	Yes	[Length and whitespace rules]
content	string	No	[Format and maximum size]

Example request

POST /v1/documents HTTP/1.1
Host: api.example.com
Authorization: Bearer <access-token>
Content-Type: application/json

{"title":"Release plan","content":"# Release plan"}

Example success response

201 Created

{
  "id": "doc_example",
  "title": "Release plan",
  "content": "# Release plan"
}

Error contract

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Title is required.",
    "requestId": "req_example"
  }
}

Status	Meaning	Consumer action
400	Invalid input	Correct the fields reported in the error.
401	Missing or invalid authentication	Authenticate again.
403	Insufficient permission	Request access; do not retry unchanged.
404	Resource unavailable	Check identifier and access policy.
429	Request limit reached	Follow the documented retry timing.
500	Unexpected service error	Capture request ID; retry only when safe.

Pagination and ordering

[Document cursor or offset parameters, defaults, maximum page size, response metadata, stable ordering, and the end-of-list condition.]

Limits, retries, and idempotency

• Limits: [Per-user or per-tenant limits, response headers, payload sizes.]
• Timeouts: [Expected timeout and client guidance.]
• Safe retries: [Which operations can be retried and under what conditions.]
• Idempotency: [Supported key, expiry, and duplicate request behavior, or explicitly unsupported.]

Versioning and support

[Describe breaking-change policy, deprecation notice, sandbox environment, and support contact.]