Endpoints in Fern Definition

Fern Definition isn’t recommended for new customers and Fern isn’t accepting feature requests for this format. It remains supported for existing users.

In Fern, you organize related endpoints into a Service. This grouping improves clarity and makes the generated SDKs more idiomatic.

Service definition

Each service defines:

A base-path: A common prefix for all the endpoints’ HTTP paths
Whether the service requires authentication
Endpoints

user.yml

1   service: 
2     base-path: /users # This defines the group/namespace for the methods
3     auth: false 
4     endpoints: {}

To define a service with an empty base path use the empty string: base-path: ""

Section display name

By default, section names in your API Reference come from service file names (e.g., user.yml becomes “User”). To override the display name of a section, use the section property in your docs.yml.

SDK method names

SDK method names are derived directly from the service file name and endpoint key. The file name becomes the namespace and the endpoint key becomes the method name.

For example, given the following definition:

users.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     create:
6       path: ""
7       method: POST
8       request: CreateUserRequest

Fern generates a method called client.users.create().

Endpoints

An endpoint includes:

A URL path (Optionally including path parameters)
A Display Name (Optional)
An HTTP Method
Request information (Optional)
- Query-parameters
- Headers
- Request body
Successful (200) response information (Optional)
Error (non-200) responses that this endpoint might return (Optional)

URL path

Each endpoint has a URL path.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET

The full path for the endpoint is the concatenation of:

The environment URL
The service base-path
The endpoint path

Endpoint display name

The display name will appear as the title of an endpoint. By default, the display name is equal to the ‘Title Case’ of the endpoint name. If you would like to customize the endpoint name, you can set the display name.

In the example below, “Add a new plant to the store” displays as the title of the endpoint page within the API Reference.

user.yml

1 service:
2   base-path: /v3
3   auth: false
4   endpoints:
5     addPlant:
6       path: /plant
7       display-name: Add a new plant to the store
8       method: POST

Path parameters

Supply path parameters for your endpoints to create dynamic URLs.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId} 
7       path-parameters: 
8         userId: string
9       method: GET

Services can also have path-parameters:

project.yml

1 service: 
2   base-path: /projects/{projectId}
3   path-parameters: 
4     projectId: string 
5   auth: false 
6   endpoints: 
7     ...

Query parameters

Each endpoint can specify query parameters:

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET
8       request:
9         # this name is required for idiomatic SDKs
10         name: GetAllUsersRequest
11         query-parameters:
12           limit: optional<integer>

`allow-multiple`

Use allow-multiple to specify that a query parameter is allowed multiple times in the URL, as in ?filter=jane&filter=smith. This will alter the generated SDKs so that consumers can provide multiple values for the query parameter.

user.yml

1   ...
2   query-parameters:
3     filter:
4       type: string
5       allow-multiple: true

Auth

Each endpoint can override the auth behavior specified in the service.

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     getMe: 
6       path: "" 
7       method: GET 
8       # This endpoint will be authed 
9       auth: true 
10       docs: Return the current user based on Authorization header.

Headers

Each endpoint can specify request headers:

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     getAllUsers: 
6       path: /all
7       method: GET 
8       request: 
9         # this name is required for idiomatic SDKs name:
10         name: GetAllUsersRequest 
11         headers: 
12           X-Endpoint-Header: string

Services can also specify request headers. These headers will cascade to the service’s endpoints.

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   headers: 
5     X-Service-Header: string 
6   endpoints: 
7     getAllUsers: 
8       path: /all 
9       method: GET 
10       request: 
11         # this name is required for idiomatic SDKs 
12         name: GetAllUsersRequest 
13         headers: 
14           X-Endpoint-Header: string

Request body

Endpoints can specify a request body type.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     setUserName:
6       path: /{userId}/set-name
7       path-parameters:
8         userId: string
9       method: POST
10       request: string

Inlining a request body

If the request body is an object, you can inline the type declaration. This makes the generated SDKs a bit more idiomatic.

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     createUser: 
6       path: /create 
7       method: POST 
8       request: 
9         # this name is required for idiomatic SDKs 
10         name: CreateUserRequest 
11         body: 
12           properties: 
13             userName: string

Success response

Endpoints can specify a response, which is the type of the body that will be returned on a successful (200) call.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET
8       response: list<User>
9 
10 types:
11   User:
12     properties:
13       userId: string
14       name: string

Response status codes

You can also use the status-code field to specify a custom status code for a success response.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     create: :
6       path: ""
7       method: POST
8       request: CreateUserRequest
9       response: 
10         type: User
11         status-code: 201
12 
13 types:
14   User:
15     properties:
16       userId: string
17       name: string

Pagination

Fern supports offset, cursor, URI, and path-based pagination schemes. To set up auto-pagination in generated SDKs:

Annotate the desired paginated endpoint with the pagination field
Specify the pagination scheme (offset, cursor, next_uri, or next_path)
Specify where your results are located using dot-access notation.

Offset pagination options

Include step in most offset pagination configurations to ensure the offset increments by the page size. Use has-next-page when your API returns a boolean indicator for additional pages.

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     list:
6       path: ""
7       method: GET
8       pagination:
9         offset: $request.page
10         step: $request.page_size # Recommended
11         results: $response.data
12         has-next-page: $response.has_more
13       request:
14         name: ListUsersRequest
15         query-parameters:
16           page: optional<integer>
17           page_size: optional<integer>
18       response: ListUsersResponse
19 
20 types:
21   ListUsersResponse:
22     properties:
23       data: list<User>
24       has_more: boolean

The pagination field supports the following properties:

Property	Description
`offset`	Path to the offset parameter in the request (e.g., `$request.page`)
`cursor`	Path to the cursor parameter in the request (e.g., `$request.cursor`)
`next_cursor`	Path to the next cursor value in the response (required for cursor pagination)
`next_uri`	Path to the next page’s URL in the response (e.g., `$response.next_page_url`)
`next_path`	Path to the relative path for the next page in the response (e.g., `$response.next_page_path`)
`results`	Path to the results array in the response (e.g., `$response.data`)
`step`	Path to the page size parameter, ensures offset increments correctly
`has-next-page`	Path to a boolean indicator for additional pages

Idempotent endpoints

Mark an endpoint as idempotent to allow SDK users to specify idempotency headers for safe request retries. You must also configure idempotency headers in your api.yml to define which headers are available.

service.yml

1 service:
2   base-path: /transactions
3   auth: true
4   endpoints:
5     send:
6       path: ""
7       method: POST
8       idempotent: true
9       request: SendTransactionRequest
10       response: Transaction

Error responses

Endpoints can specify error responses, which detail the non-200 responses that the endpoint might return.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId}
7       path-parameters:
8         userId: string
9       method: GET
10       response: User
11       errors:
12         - UserNotFoundError
13 
14 types:
15   User:
16     properties:
17       userId: string
18       name: string
19 
20 errors:
21   UserNotFoundError:
22     status-code: 404

You can learn more about how to define errors on the Errors page.

Specifying examples

When you declare an example, you can also specify some examples of how that endpoint might be used. These are used by the compiler to enhance the generated outputs. Examples will show up as comments in your SDKs, API documentation, and Postman collection.

You may add examples for endpoints, types, and errors.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId}
7       path-parameters:
8         userId: string
9       method: GET
10       response: User
11       errors:
12         - UserNotFoundError
13       examples:
14         - path-parameters:
15             userId: alice-user-id
16           response:
17             body:
18               userId: alice-user-id
19               name: Alice
20 
21 types:
22   User:
23     properties:
24       userId: string
25       name: string
26 
27 errors:
28   UserNotFoundError:
29     status-code: 404

If you’re adding an example to an endpoint and the type already has an example, you can reference it using $.

1 service:
2   auth: true
3   base-path: /address
4   endpoints:
5     create:
6       method: POST
7       path: ""
8       request: CreateAddress
9       response: Address
10       examples:
11         - request: $CreateAddress.WhiteHouse
12           response:
13             body: $Address.WhiteHouseWithID
14 
15   CreateAddress:
16     properties:
17       street1: string
18       street2: optional<string>
19       city: string
20       state: string
21       postalCode: string
22       country: string
23       isResidential: boolean
24     examples:
25       - name: WhiteHouse
26         value:
27           street1: 1600 Pennsylvania Avenue NW
28           city: Washington DC
29           state: Washington DC
30           postalCode: "20500"
31           country: US
32           isResidential: true
33 
34   Address:
35     extends: CreateAddress
36     properties:
37       id:
38         type: uuid
39         docs: The unique identifier for the address.
40     examples:
41       - name: WhiteHouseWithID
42         value:
43           id: 65ce514c-41e3-11ee-be56-0242ac120002
44           street1: 1600 Pennsylvania Avenue NW
45           city: Washington DC
46           state: Washington DC
47           postalCode: "20500"
48           country: US
49           isResidential: true

Examples contain all the information about the endpoint call, including the request body, path parameters, query parameters, headers, and response body.

user.yml

1 examples: 
2   - path-parameters: 
3       userId: some-user-id 
4     query-parameters:
5       limit: 50 
6     headers: 
7       X-My-Header: some-value 
8     response: 
9       body: 
10         response-field: hello

Failed examples

You can also specify examples of failed endpoints calls. Add the error property to a response example to designate which failure you’re demonstrating.

user.yml

1 examples:
2   - path-parameters:
3       userId: missing-user-id
4     response:
5       error: UserNotFoundError
6 
7 errors:
8   UserNotFoundError:
9     status-code: 404

If the error has a body, then you must include the body in the example.

user.yml

1 examples:
2   - path-parameters:
3       userId: missing-user-id
4     response:
5       error: UserNotFoundError
6       body: "User with id `missing-user-id` was not found"
7 
8 errors:
9   UserNotFoundError:
10     status-code: 404
11     type: string

Referencing examples from types

To avoid duplication, you can reference examples from types using $.

user.yml

1 service:
2   base-path: /users
3   auth: true
4   endpoints:
5     getUser:
6       method: GET
7       path: /{userId}
8       path-parameters:
9         userId: UserId
10       examples:
11         - path-parameters:
12             userId: $UserId.Example1
13 
14 types:
15   UserId:
16   type: integer
17   examples: 
18     - name: Example1
19       value: user-id-123

Fern Definition isn’t recommended for new customers and Fern isn’t accepting feature requests for this format. It remains supported for existing users.

In Fern, you organize related endpoints into a Service. This grouping improves clarity and makes the generated SDKs more idiomatic.

Service definition

Each service defines:

A base-path: A common prefix for all the endpoints’ HTTP paths
Whether the service requires authentication
Endpoints

user.yml

1   service: 
2     base-path: /users # This defines the group/namespace for the methods
3     auth: false 
4     endpoints: {}

To define a service with an empty base path use the empty string: base-path: ""

Section display name

SDK method names

SDK method names are derived directly from the service file name and endpoint key. The file name becomes the namespace and the endpoint key becomes the method name.

For example, given the following definition:

users.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     create:
6       path: ""
7       method: POST
8       request: CreateUserRequest

Fern generates a method called client.users.create().

Endpoints

An endpoint includes:

A URL path (Optionally including path parameters)
A Display Name (Optional)
An HTTP Method
Request information (Optional)
- Query-parameters
- Headers
- Request body
Successful (200) response information (Optional)
Error (non-200) responses that this endpoint might return (Optional)

URL path

Each endpoint has a URL path.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET

The full path for the endpoint is the concatenation of:

The environment URL
The service base-path
The endpoint path

Endpoint display name

In the example below, “Add a new plant to the store” displays as the title of the endpoint page within the API Reference.

user.yml

1 service:
2   base-path: /v3
3   auth: false
4   endpoints:
5     addPlant:
6       path: /plant
7       display-name: Add a new plant to the store
8       method: POST

Path parameters

Supply path parameters for your endpoints to create dynamic URLs.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId} 
7       path-parameters: 
8         userId: string
9       method: GET

Services can also have path-parameters:

project.yml

1 service: 
2   base-path: /projects/{projectId}
3   path-parameters: 
4     projectId: string 
5   auth: false 
6   endpoints: 
7     ...

Query parameters

Each endpoint can specify query parameters:

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET
8       request:
9         # this name is required for idiomatic SDKs
10         name: GetAllUsersRequest
11         query-parameters:
12           limit: optional<integer>

`allow-multiple`

user.yml

1   ...
2   query-parameters:
3     filter:
4       type: string
5       allow-multiple: true

Auth

Each endpoint can override the auth behavior specified in the service.

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     getMe: 
6       path: "" 
7       method: GET 
8       # This endpoint will be authed 
9       auth: true 
10       docs: Return the current user based on Authorization header.

Headers

Each endpoint can specify request headers:

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     getAllUsers: 
6       path: /all
7       method: GET 
8       request: 
9         # this name is required for idiomatic SDKs name:
10         name: GetAllUsersRequest 
11         headers: 
12           X-Endpoint-Header: string

Services can also specify request headers. These headers will cascade to the service’s endpoints.

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   headers: 
5     X-Service-Header: string 
6   endpoints: 
7     getAllUsers: 
8       path: /all 
9       method: GET 
10       request: 
11         # this name is required for idiomatic SDKs 
12         name: GetAllUsersRequest 
13         headers: 
14           X-Endpoint-Header: string

Request body

Endpoints can specify a request body type.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     setUserName:
6       path: /{userId}/set-name
7       path-parameters:
8         userId: string
9       method: POST
10       request: string

Inlining a request body

If the request body is an object, you can inline the type declaration. This makes the generated SDKs a bit more idiomatic.

user.yml

1 service: 
2   base-path: /users 
3   auth: false 
4   endpoints: 
5     createUser: 
6       path: /create 
7       method: POST 
8       request: 
9         # this name is required for idiomatic SDKs 
10         name: CreateUserRequest 
11         body: 
12           properties: 
13             userName: string

Success response

Endpoints can specify a response, which is the type of the body that will be returned on a successful (200) call.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getAllUsers:
6       path: /all
7       method: GET
8       response: list<User>
9 
10 types:
11   User:
12     properties:
13       userId: string
14       name: string

Response status codes

You can also use the status-code field to specify a custom status code for a success response.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     create: :
6       path: ""
7       method: POST
8       request: CreateUserRequest
9       response: 
10         type: User
11         status-code: 201
12 
13 types:
14   User:
15     properties:
16       userId: string
17       name: string

Pagination

Fern supports offset, cursor, URI, and path-based pagination schemes. To set up auto-pagination in generated SDKs:

Annotate the desired paginated endpoint with the pagination field
Specify the pagination scheme (offset, cursor, next_uri, or next_path)
Specify where your results are located using dot-access notation.

Offset pagination options

Include step in most offset pagination configurations to ensure the offset increments by the page size. Use has-next-page when your API returns a boolean indicator for additional pages.

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     list:
6       path: ""
7       method: GET
8       pagination:
9         offset: $request.page
10         step: $request.page_size # Recommended
11         results: $response.data
12         has-next-page: $response.has_more
13       request:
14         name: ListUsersRequest
15         query-parameters:
16           page: optional<integer>
17           page_size: optional<integer>
18       response: ListUsersResponse
19 
20 types:
21   ListUsersResponse:
22     properties:
23       data: list<User>
24       has_more: boolean

The pagination field supports the following properties:

Property	Description
`offset`	Path to the offset parameter in the request (e.g., `$request.page`)
`cursor`	Path to the cursor parameter in the request (e.g., `$request.cursor`)
`next_cursor`	Path to the next cursor value in the response (required for cursor pagination)
`next_uri`	Path to the next page’s URL in the response (e.g., `$response.next_page_url`)
`next_path`	Path to the relative path for the next page in the response (e.g., `$response.next_page_path`)
`results`	Path to the results array in the response (e.g., `$response.data`)
`step`	Path to the page size parameter, ensures offset increments correctly
`has-next-page`	Path to a boolean indicator for additional pages

Idempotent endpoints

service.yml

1 service:
2   base-path: /transactions
3   auth: true
4   endpoints:
5     send:
6       path: ""
7       method: POST
8       idempotent: true
9       request: SendTransactionRequest
10       response: Transaction

Error responses

Endpoints can specify error responses, which detail the non-200 responses that the endpoint might return.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId}
7       path-parameters:
8         userId: string
9       method: GET
10       response: User
11       errors:
12         - UserNotFoundError
13 
14 types:
15   User:
16     properties:
17       userId: string
18       name: string
19 
20 errors:
21   UserNotFoundError:
22     status-code: 404

You can learn more about how to define errors on the Errors page.

Specifying examples

You may add examples for endpoints, types, and errors.

user.yml

1 service:
2   base-path: /users
3   auth: false
4   endpoints:
5     getUser:
6       path: /{userId}
7       path-parameters:
8         userId: string
9       method: GET
10       response: User
11       errors:
12         - UserNotFoundError
13       examples:
14         - path-parameters:
15             userId: alice-user-id
16           response:
17             body:
18               userId: alice-user-id
19               name: Alice
20 
21 types:
22   User:
23     properties:
24       userId: string
25       name: string
26 
27 errors:
28   UserNotFoundError:
29     status-code: 404

If you’re adding an example to an endpoint and the type already has an example, you can reference it using $.

1 service:
2   auth: true
3   base-path: /address
4   endpoints:
5     create:
6       method: POST
7       path: ""
8       request: CreateAddress
9       response: Address
10       examples:
11         - request: $CreateAddress.WhiteHouse
12           response:
13             body: $Address.WhiteHouseWithID
14 
15   CreateAddress:
16     properties:
17       street1: string
18       street2: optional<string>
19       city: string
20       state: string
21       postalCode: string
22       country: string
23       isResidential: boolean
24     examples:
25       - name: WhiteHouse
26         value:
27           street1: 1600 Pennsylvania Avenue NW
28           city: Washington DC
29           state: Washington DC
30           postalCode: "20500"
31           country: US
32           isResidential: true
33 
34   Address:
35     extends: CreateAddress
36     properties:
37       id:
38         type: uuid
39         docs: The unique identifier for the address.
40     examples:
41       - name: WhiteHouseWithID
42         value:
43           id: 65ce514c-41e3-11ee-be56-0242ac120002
44           street1: 1600 Pennsylvania Avenue NW
45           city: Washington DC
46           state: Washington DC
47           postalCode: "20500"
48           country: US
49           isResidential: true

Examples contain all the information about the endpoint call, including the request body, path parameters, query parameters, headers, and response body.

user.yml

1 examples: 
2   - path-parameters: 
3       userId: some-user-id 
4     query-parameters:
5       limit: 50 
6     headers: 
7       X-My-Header: some-value 
8     response: 
9       body: 
10         response-field: hello

Failed examples

You can also specify examples of failed endpoints calls. Add the error property to a response example to designate which failure you’re demonstrating.

user.yml

1 examples:
2   - path-parameters:
3       userId: missing-user-id
4     response:
5       error: UserNotFoundError
6 
7 errors:
8   UserNotFoundError:
9     status-code: 404

If the error has a body, then you must include the body in the example.

user.yml

1 examples:
2   - path-parameters:
3       userId: missing-user-id
4     response:
5       error: UserNotFoundError
6       body: "User with id `missing-user-id` was not found"
7 
8 errors:
9   UserNotFoundError:
10     status-code: 404
11     type: string

Referencing examples from types

To avoid duplication, you can reference examples from types using $.

user.yml

1 service:
2   base-path: /users
3   auth: true
4   endpoints:
5     getUser:
6       method: GET
7       path: /{userId}
8       path-parameters:
9         userId: UserId
10       examples:
11         - path-parameters:
12             userId: $UserId.Example1
13 
14 types:
15   UserId:
16   type: integer
17   examples: 
18     - name: Example1
19       value: user-id-123

1	service:
2	base-path: /users # This defines the group/namespace for the methods
3	auth: false
4	endpoints: {}

1	service:
2	base-path: /users
3	auth: false
4	endpoints:
5	create:
6	path: ""
7	method: POST
8	request: CreateUserRequest

1	service:
2	base-path: /v3
3	auth: false
4	endpoints:
5	addPlant:
6	path: /plant
7	display-name: Add a new plant to the store
8	method: POST

1	service:
2	base-path: /projects/{projectId}
3	path-parameters:
4	projectId: string
5	auth: false
6	endpoints:
7	...

1	...
2	query-parameters:
3	filter:
4	type: string
5	allow-multiple: true

1	service:
2	base-path: /transactions
3	auth: true
4	endpoints:
5	send:
6	path: ""
7	method: POST
8	idempotent: true
9	request: SendTransactionRequest
10	response: Transaction

1	service:
2	auth: true
3	base-path: /address
4	endpoints:
5	create:
6	method: POST
7	path: ""
8	request: CreateAddress
9	response: Address
10	examples:
11	- request: $CreateAddress.WhiteHouse
12	response:
13	body: $Address.WhiteHouseWithID
14
15	CreateAddress:
16	properties:
17	street1: string
18	street2: optional<string>
19	city: string
20	state: string
21	postalCode: string
22	country: string
23	isResidential: boolean
24	examples:
25	- name: WhiteHouse
26	value:
27	street1: 1600 Pennsylvania Avenue NW
28	city: Washington DC
29	state: Washington DC
30	postalCode: "20500"
31	country: US
32	isResidential: true
33
34	Address:
35	extends: CreateAddress
36	properties:
37	id:
38	type: uuid
39	docs: The unique identifier for the address.
40	examples:
41	- name: WhiteHouseWithID
42	value:
43	id: 65ce514c-41e3-11ee-be56-0242ac120002
44	street1: 1600 Pennsylvania Avenue NW
45	city: Washington DC
46	state: Washington DC
47	postalCode: "20500"
48	country: US
49	isResidential: true

1	examples:
2	- path-parameters:
3	userId: some-user-id
4	query-parameters:
5	limit: 50
6	headers:
7	X-My-Header: some-value
8	response:
9	body:
10	response-field: hello

1	examples:
2	- path-parameters:
3	userId: missing-user-id
4	response:
5	error: UserNotFoundError
6
7	errors:
8	UserNotFoundError:
9	status-code: 404