Ariadocs

Edge cases

Edit on GitHub

One endpoint that uses every part of OpenAPI the components render.

This page renders a test spec, edge-cases.yaml. It isn't a real API. Its one endpoint puts every case in one place, so you can check how the components handle each one:

  • parameters in the path, query, header and cookie, with enums, limits, defaults, a deprecated parameter and an array sent as a,b,
  • three ways to authenticate (a bearer token, an API key plus OAuth scopes, or none),
  • a body in JSON, multipart and URL-encoded form,
  • allOf, oneOf with a discriminator, anyOf with null, a schema that contains itself, maps, read-only, write-only and deprecated fields,
  • 2xx, 3xx, 4xx, a 5XX range and a default response, some with headers,
  • Markdown in the description, including a javascript: link that has to render as plain text,
  • a server URL with variables.

The endpoint

Preview

Items

Create an item

POSThttps://eu.api.example.com/v2/projects/{project_id}/items

Creates an item in a project. The request can be JSON, a multipart upload or a URL-encoded form.

Things to know

  • Items are validated before they are saved.
  • A request with the same Idempotency-Key returns the first result.
  • Large uploads return 202 and finish in the background.
json
{ "kind": "note", "title": "Hello" }

Read the guide. This link is unsafe and must render as text.

Authorization

optional
Authorizationheaderrequired

Bearer authentication (JWT): Bearer <token>.

or

X-API-Keyheaderrequired

API key (apiKey).

Authorizationheaderrequired

OAuth 2.0 access token (oauth): Bearer <token>.

Scopes: items:writeitems:read

Path Parameters

project_idstringrequired

The project to add the item to.

Pattern: "^prj_[a-z0-9]{12}$"

Example: prj_8f2k1m9x0a3b

Query Parameters

dry_runboolean

Validate the request without saving anything.

Default: false
fieldsstring[]

Fields to include in the response.

≥ 1 itemsUnique items

Example: ["id","title"]

priorityintegerrequired
Default: 3Range: >= 1, <= 5
legacy_modestringdeprecated

Old behavior. Will be removed in v3.

Header Parameters

Idempotency-Keystring<uuid>

A unique key so retries don't create duplicates.

≤ 64 length

Cookie Parameters

Body

The item to create.

titlestringrequired
1 to 200 length
tagsstring[]
≤ 10 itemsUnique items
contentNote | Task

Either a note or a task.

ownerobject | null

Who owns the item. null means the project.

visibilitystring
Default: "private"One of: "private""team""public"
scorenumber
Range: > 0, <= 100Multiple of 0.5
metadataobject

Any extra string values.

outlineNode

A tree node. Children are nodes too.

secretstring<password>write-only

Never returned in responses.

colorstringdeprecated

Use visibility instead.

Responses

201

The item was created.

202

The upload was accepted and is processed in the background.

204

Nothing was saved because dry_run was true.

303

An item with this idempotency key already exists.

400

A problem with the request.

401

Missing or invalid credentials.

409

An item with this title already exists in the project.

422

The item failed validation.

429

Too many requests.

5XX

Something went wrong on our side.

default

A problem with the request.

curl -X POST 'https://eu.api.example.com/v2/projects/prj_8f2k1m9x0a3b/items?dry_run=false&fields=id%2Ctitle&priority=3' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "kind": "note",
  "title": "Shopping list",
  "body": "Milk, eggs",
  "tags": [
    "home"
  ]
}'
Response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "string",
  "tags": [
    "string"
  ],
  "content": {
    "kind": "note",
    "body": "string"
  },
  "owner": {
    "user_id": "string",
    "email": "user@example.com"
  },
  "visibility": "private",
  "score": 1,
  "metadata": {},
  "outline": {
    "label": "string",
    "children": [
      null
    ]
  },
  "color": "string",
  "created_at": "2024-01-01T00:00:00Z"
}

Schemas

The request body:

Preview
CreateItemobject
titlestringrequired
1 to 200 length
tagsstring[]
≤ 10 itemsUnique items
contentNote | Task

Either a note or a task.

ownerobject | null

Who owns the item. null means the project.

visibilitystring
Default: "private"One of: "private""team""public"
scorenumber
Range: > 0, <= 100Multiple of 0.5
metadataobject

Any extra string values.

outlineNode

A tree node. Children are nodes too.

secretstring<password>write-only

Never returned in responses.

colorstringdeprecated

Use visibility instead.

The error format:

Preview
Problemobject
typestring<uri>required
titlestringrequired
statusinteger
detailstring | null

The API overview

Preview
v1.0.0OpenAPI 3.1.0

Ariadocs edge cases

A test fixture, not a real API.

One endpoint that uses every part of OpenAPI the @ariadocs/components package renders. Use it to check how the components handle unusual specs.

License: MIT

Base URL

  • https://eu.api.example.com/v2Regional API

Server variables are filled in with their defaults.

Authorization

Authorizationheaderrequired

Bearer authentication (JWT): Bearer <token>.