> ## 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.

# Type-Level Search

> Search within a specific resource type

## Type-Level Search

Search for resources of a specific type using search parameters.

<ParamField path="resource_type" type="string" required>
  The FHIR resource type to search (e.g., `Patient`, `Observation`, `Encounter`)
</ParamField>

## Endpoint

```
GET /fhir/:resource_type
GET /fhir/:resource_type/_search
POST /fhir/:resource_type/_search
```

## GET Request

Search using query parameters:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://your-server.com/fhir/Patient?name=Doe&gender=male&_count=10"
  ```

  ```bash HTTP theme={null}
  GET /fhir/Patient?name=Doe&gender=male&_count=10 HTTP/1.1
  Host: your-server.com
  ```
</CodeGroup>

## POST Request

Use POST for complex searches or when query string length is a concern:

```json theme={null}
POST /fhir/Patient/_search
Content-Type: application/x-www-form-urlencoded

name=Doe&gender=male&_count=10
```

## Search Parameters

Search parameters are resource-type specific. Common examples:

### Patient Search

* `name` - Search by patient name
* `identifier` - Search by identifier (e.g., `identifier=http://example.org/mrn|12345`)
* `gender` - Filter by gender (`male`, `female`, `other`, `unknown`)
* `birthdate` - Filter by birth date (supports prefixes: `eq`, `gt`, `lt`, `ge`, `le`)
* `address` - Search by address
* `telecom` - Search by contact information

### Observation Search

* `patient` - Filter by patient reference
* `code` - Filter by observation code
* `date` - Filter by observation date
* `value-quantity` - Filter by value
* `status` - Filter by status

### Common Parameters (All Types)

* `_id` - Filter by resource ID
* `_lastUpdated` - Filter by last updated date
* `_tag` - Filter by tags
* `_profile` - Filter by profile
* `_security` - Filter by security labels
* `_count` - Maximum number of results
* `_sort` - Sort order
* `_summary` - Summary mode
* `_total` - Include total count

## Examples

### Search Patients by Name

```bash theme={null}
GET /fhir/Patient?name=Doe
```

### Search Patients by Identifier

```bash theme={null}
GET /fhir/Patient?identifier=http://example.org/mrn|12345
```

### Search Observations for a Patient

```bash theme={null}
GET /fhir/Observation?patient=Patient/123&code=http://loinc.org|29463-7
```

### Search with Date Range

```bash theme={null}
GET /fhir/Observation?patient=Patient/123&date=ge2024-01-01&date=le2024-12-31
```

### Search with Multiple Parameters

```bash theme={null}
GET /fhir/Patient?name=Doe&gender=male&birthdate=ge1990-01-01&_count=20&_sort=-birthdate
```

## Response

### Success (200 OK)

Returns a `Bundle` containing matching resources:

```json theme={null}
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 5,
  "link": [
    {
      "relation": "self",
      "url": "https://your-server.com/fhir/Patient?name=Doe"
    }
  ],
  "entry": [
    {
      "fullUrl": "https://your-server.com/fhir/Patient/123",
      "resource": {
        "resourceType": "Patient",
        "id": "123",
        "name": [{"family": "Doe", "given": ["John"]}],
        ...
      }
    }
  ]
}
```

### No Results

Returns an empty bundle if no resources match:

```json theme={null}
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 0,
  "entry": []
}
```

## Modifiers

Search parameters support modifiers:

* `:exact` - Exact match
* `:contains` - Contains substring
* `:text` - Text search
* `:above` - Above in hierarchy
* `:below` - Below in hierarchy
* `:not` - Negation
* `:in` - Value in set
* `:not-in` - Value not in set

### Example with Modifiers

```bash theme={null}
GET /fhir/Patient?name:contains=John&birthdate:ge1990-01-01
```

## Chaining

Chain searches through references:

```bash theme={null}
GET /fhir/Observation?patient.name=Doe&patient.gender=male
```

This searches for observations where the patient's name is "Doe" and gender is "male".

## Reverse Chaining

Search resources that reference a specific resource:

```bash theme={null}
GET /fhir/Observation?_has:Patient:identifier=http://example.org/mrn|12345
```

This finds observations for patients with a specific identifier.

## Notes

* Search parameters are case-sensitive
* Multiple values for the same parameter use AND logic
* Different parameters use AND logic
* Use `_include` and `_revinclude` to include related resources
* Check the resource's search parameters in the capability statement


## OpenAPI

````yaml GET /{resourceType}
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:
  /{resourceType}:
    get:
      tags:
        - Search
      summary: Search Resources by Type
      description: Search for resources of a specific type using search parameters.
      operationId: searchType
      parameters:
        - $ref: '#/components/parameters/ResourceType'
        - $ref: '#/components/parameters/Count'
        - $ref: '#/components/parameters/Sort'
        - $ref: '#/components/parameters/Summary'
        - $ref: '#/components/parameters/Total'
        - $ref: '#/components/parameters/LastUpdated'
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: Search results
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
            application/fhir+xml:
              schema:
                $ref: '#/components/schemas/Bundle'
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  parameters:
    ResourceType:
      name: resourceType
      in: path
      required: true
      description: The FHIR resource type (e.g., Patient, Observation, Encounter)
      schema:
        type: string
    Count:
      name: _count
      in: query
      description: Maximum number of results to return
      schema:
        type: integer
        minimum: 0
        default: 10
    Sort:
      name: _sort
      in: query
      description: Sort order (prefix with - for descending)
      schema:
        type: string
    Summary:
      name: _summary
      in: query
      description: Summary mode
      schema:
        type: string
        enum:
          - 'true'
          - text
          - data
          - count
    Total:
      name: _total
      in: query
      description: Include total count
      schema:
        type: string
        enum:
          - none
          - estimate
          - accurate
    LastUpdated:
      name: _lastUpdated
      in: query
      description: Filter by last updated date
      schema:
        type: string
    Id:
      name: id
      in: path
      required: true
      description: The logical ID of the resource
      schema:
        type: string
  schemas:
    Bundle:
      type: object
      description: A container for a collection of resources
      required:
        - resourceType
        - type
      properties:
        resourceType:
          type: string
          enum:
            - Bundle
          description: Resource type
        type:
          type: string
          enum:
            - document
            - message
            - transaction
            - transaction-response
            - batch
            - batch-response
            - history
            - searchset
            - collection
          description: Indicates the purpose of this bundle
        total:
          type: integer
          description: If search, the total number of matches
        link:
          type: array
          items:
            $ref: '#/components/schemas/BundleLink'
          description: Links related to this Bundle
        entry:
          type: array
          items:
            $ref: '#/components/schemas/BundleEntry'
          description: Entry in the bundle
    BundleLink:
      type: object
      description: A link to another resource
      properties:
        relation:
          type: string
          description: >-
            See
            http://www.iana.org/assignments/link-relations/link-relations.xhtml#link-relations-1
        url:
          type: string
          format: uri
          description: Reference details for the link
    BundleEntry:
      type: object
      description: An entry in a bundle resource
      properties:
        fullUrl:
          type: string
          format: uri
          description: URI for resource
        resource:
          $ref: '#/components/schemas/Resource'
        request:
          $ref: '#/components/schemas/BundleEntryRequest'
        response:
          $ref: '#/components/schemas/BundleEntryResponse'
    OperationOutcome:
      type: object
      description: >-
        A collection of error, warning or information messages that result from
        a system action
      required:
        - resourceType
      properties:
        resourceType:
          type: string
          enum:
            - OperationOutcome
          description: Resource type
        issue:
          type: array
          items:
            $ref: '#/components/schemas/OperationOutcomeIssue'
          description: A list of issues associated with the operation
    Resource:
      type: object
      description: A FHIR resource. All resources have resourceType, id, and meta fields.
      required:
        - resourceType
      properties:
        resourceType:
          type: string
          description: The type of resource
        id:
          type: string
          description: Logical id of this artifact
        meta:
          $ref: '#/components/schemas/Meta'
      additionalProperties: true
    BundleEntryRequest:
      type: object
      description: Additional information about how this entry should be processed
      properties:
        method:
          type: string
          enum:
            - GET
            - POST
            - PUT
            - PATCH
            - DELETE
          description: HTTP verb for the operation
        url:
          type: string
          description: URL for HTTP equivalent of this entry
    BundleEntryResponse:
      type: object
      description: Indicates the results of processing the corresponding 'request' entry
      properties:
        status:
          type: string
          description: Status response code
        location:
          type: string
          description: The location (if the operation returns a location)
        etag:
          type: string
          description: The etag for the resource (if relevant)
        lastModified:
          type: string
          format: date-time
          description: Server's date time modified
        outcome:
          $ref: '#/components/schemas/OperationOutcome'
    OperationOutcomeIssue:
      type: object
      description: An issue associated with the operation
      required:
        - severity
        - code
      properties:
        severity:
          type: string
          enum:
            - fatal
            - error
            - warning
            - information
          description: Severity of the issue
        code:
          type: string
          enum:
            - invalid
            - structure
            - required
            - value
            - invariant
            - security
            - login
            - unknown
            - expired
            - forbidden
            - suppressed
            - processing
            - not-supported
            - duplicate
            - multiple-matches
            - not-found
            - deleted
            - too-long
            - code-invalid
            - extension
            - too-costly
            - business-rule
            - conflict
            - transient
            - lock-error
            - no-store
            - exception
            - timeout
            - incomplete
            - throttled
            - informational
          description: Error or warning code
        details:
          $ref: '#/components/schemas/CodeableConcept'
        diagnostics:
          type: string
          description: Additional diagnostic information about the issue
        location:
          type: array
          items:
            type: string
          description: XPath or JSONPath expression describing the location of the issue
    Meta:
      type: object
      description: Metadata about a resource
      properties:
        versionId:
          type: string
          description: Version specific identifier
        lastUpdated:
          type: string
          format: date-time
          description: When the resource version last changed
        profile:
          type: array
          items:
            type: string
            format: uri
          description: Profiles this resource claims to conform to
        tag:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
          description: Tags applied to this resource
        security:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
          description: Security labels applied to this resource
    CodeableConcept:
      type: object
      description: >-
        A concept that may be defined by a formal reference to a terminology or
        ontology
      properties:
        coding:
          type: array
          items:
            $ref: '#/components/schemas/Coding'
        text:
          type: string
          description: Plain text representation of the concept
    Coding:
      type: object
      description: A reference to a code defined by a terminology system
      properties:
        system:
          type: string
          format: uri
          description: Identity of the terminology system
        version:
          type: string
          description: Version of the system - if relevant
        code:
          type: string
          description: Symbol in syntax defined by the system
        display:
          type: string
          description: Representation defined by the system
  responses:
    BadRequest:
      description: Bad request - validation error or invalid input
      content:
        application/fhir+json:
          schema:
            $ref: '#/components/schemas/OperationOutcome'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token authentication

````