> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ferrum.thalamiq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Capability Statement

> Get server capabilities and configuration

## Capability Statement

Retrieve the server's capability statement, which describes the server's capabilities, supported resources, search parameters, and operations.

## Endpoint

```
GET /fhir/metadata
```

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "Accept: application/fhir+json" \
       https://your-server.com/fhir/metadata
  ```

  ```bash HTTP theme={null}
  GET /fhir/metadata HTTP/1.1
  Host: your-server.com
  Accept: application/fhir+json
  ```
</CodeGroup>

## Response

### Success (200 OK)

Returns a `CapabilityStatement` resource:

```json theme={null}
{
  "resourceType": "CapabilityStatement",
  "status": "active",
  "date": "2024-01-01T12:00:00Z",
  "kind": "instance",
  "software": {
    "name": "Ferrum",
    "version": "1.0.0"
  },
  "implementation": {
    "url": "https://your-server.com/fhir",
    "description": "Ferrum Implementation"
  },
  "fhirVersion": "4.0.1",
  "format": [
    "application/fhir+json",
    "application/fhir+xml"
  ],
  "rest": [
    {
      "mode": "server",
      "resource": [
        {
          "type": "Patient",
          "interaction": [
            {
              "code": "read"
            },
            {
              "code": "vread"
            },
            {
              "code": "update"
            },
            {
              "code": "patch"
            },
            {
              "code": "delete"
            },
            {
              "code": "history-instance"
            },
            {
              "code": "history-type"
            },
            {
              "code": "create"
            },
            {
              "code": "search-type"
            }
          ],
          "searchParam": [
            {
              "name": "name",
              "type": "string",
              "documentation": "A server defined search that may match any of the string fields in the HumanName, including family, given, prefix, suffix, and/or text"
            },
            {
              "name": "identifier",
              "type": "token",
              "documentation": "A patient identifier"
            }
          ]
        }
      ]
    }
  ]
}
```

## Capability Statement Structure

The capability statement includes:

### Software Information

* `software.name` - Server name
* `software.version` - Server version
* `software.releaseDate` - Release date

### Implementation Details

* `implementation.url` - Base URL
* `implementation.description` - Implementation description

### Supported Formats

* `format` - List of supported content types (JSON, XML, etc.)

### REST Capabilities

* `rest.mode` - Server mode (`server` or `client`)
* `rest.resource` - List of supported resources

### Resource Capabilities

For each resource type:

* `type` - Resource type name
* `interaction` - Supported interactions (read, create, update, delete, search, etc.)
* `searchParam` - Supported search parameters
* `operation` - Supported operations
* `versioning` - Versioning support (`versioned`, `versioned-update`, `no-version`, `versioned`)
* `readHistory` - Whether history is supported
* `updateCreate` - Whether updates can create resources
* `conditionalCreate` - Whether conditional create is supported
* `conditionalUpdate` - Whether conditional update is supported
* `conditionalDelete` - Whether conditional delete is supported

### Operations

* `rest.operation` - System-level operations
* `rest.resource[].operation` - Resource-specific operations

## Use Cases

Use the capability statement to:

* Discover which resources are supported
* Learn which search parameters are available
* Check which operations are supported
* Determine versioning behavior
* Understand server capabilities before making requests

## Notes

* The capability statement is always available at `/fhir/metadata`
* It reflects the current server configuration
* Use it to build dynamic clients that adapt to server capabilities
* The statement may change as the server is updated or configured


## OpenAPI

````yaml GET /metadata
openapi: 3.1.0
info:
  title: Ferrum API
  description: >-
    FHIR R4 RESTful API implementation. All endpoints are prefixed with `/fhir`
    and follow the FHIR specification.
  version: 1.0.0
  contact:
    name: Ferrum
    url: https://github.com/thalamiq/ferrum
  license:
    name: MIT
servers:
  - url: http://localhost:8080/fhir
    description: Local development server (default port 8080)
  - url: https://your-server.com/fhir
    description: Production server (replace with your actual server URL)
  - url: https://api.example.com/fhir
    description: Example production server
security:
  - bearerAuth: []
paths:
  /metadata:
    get:
      tags:
        - Metadata
      summary: Get Capability Statement
      description: >-
        Retrieve the server's capability statement describing supported
        resources, operations, and search parameters.
      operationId: getCapabilityStatement
      responses:
        '200':
          description: Capability statement
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/CapabilityStatement'
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/CapabilityStatement'
components:
  schemas:
    CapabilityStatement:
      type: object
      description: >-
        A Capability Statement documents a set of capabilities (behaviors) of a
        FHIR Server
      required:
        - resourceType
      properties:
        resourceType:
          type: string
          enum:
            - CapabilityStatement
        status:
          type: string
          enum:
            - draft
            - active
            - retired
            - unknown
        date:
          type: string
          format: date-time
        kind:
          type: string
          enum:
            - instance
            - capability
            - requirements
        software:
          type: object
          properties:
            name:
              type: string
            version:
              type: string
        fhirVersion:
          type: string
        format:
          type: array
          items:
            type: string
        rest:
          type: array
          items:
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication

````