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

# /v1/search

Returns sourced, structured answers to natural-language questions.

<ParamField header="X-API-Key" type="string" required>
  API key used for authentication.
</ParamField>

<ParamField header="x-cache-ttl" type="integer">
  Optional cache lifetime hint in seconds for successful GETs. Valid range is 0–3600. Set to 0 to disable caching for this response.
</ParamField>

<ParamField query="query" type="string" required>
  Natural-language question to answer. Always URL-encode when calling via raw HTTP.
</ParamField>

## Recommended usage (SDKs)

Use the official SDKs whenever possible. They handle base URLs, retries, timeouts, and typed responses for you.

<CodeGroup>
  ```python Python (usdk) theme={null}
  import os
  from uapi import uAPI

  client = uAPI(api_key=os.environ.get("UAPI_API_KEY"))

  resp = client.search(
      query="When is the next solar eclipse visible from Europe?"
  )

  print(resp.data.answer_text)
  for src in resp.data.sources:
      print("-", src.title, src.url)
  ```

  ```javascript Node.js / TypeScript (usdk-js) theme={null}
  import uAPI from 'usdk-js'

  const client = new uAPI({
    apiKey: process.env.UAPI_API_KEY,
  })

  const resp = await client.search({
    query: 'When is the next solar eclipse visible from Europe?',
  })

  console.log(resp.data.answer_text)
  console.log(resp.data.sources)
  ```

  ```bash cURL theme={null}
  curl -s "https://api.uapi.nl/v1/search?query=When%20is%20the%20next%20solar%20eclipse%20visible%20from%20Europe%3F" \
    -H "X-API-Key: ${UAPI_API_KEY}"
  ```
</CodeGroup>

## Example response

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "id":"ab178130-3d07-452c-bde0-1135545145de",
    "data":{
  	"answer_text":"The next solar eclipse that will be visible from Europe occurs on 12 August 2026, when a high‑magnitude partial eclipse (covering about 90 % of the Sun) will be observable across much of the continent.",
      "sources":[
        {
          "url":"https://www.timeanddate.com/eclipse/list.html?region=europe&type=total-solar",
          "title":"Total Solar Eclipses in Europe – Next 10 Years - Time and Date"
        },
        {
          "url":"https://www.timeanddate.com/eclipse/europe.html",
          "title":"Solar and Lunar Eclipses in Europe – Next 10 Years - Time and Date"
        },
        {
          "url":"https://en.wikipedia.org/wiki/Solar_eclipse_of_August_12,_2026",
          "title":"Solar eclipse of August 12, 2026 - Wikipedia"
        },
        {
          "url":"https://www.rmg.co.uk/stories/space-astronomy/solar-eclipses-explained",
          "title":"Solar eclipses explained: dates, types, how to see safely"
        },
        {
          "url":"https://nso.edu/for-public/eclipse-map-2026/",
          "title":"August 12, 2026 Solar Eclipse Map - NSO"
        },
        {
          "url":"https://nationaleclipse.com/maps_upcoming.html",
          "title":"Upcoming Eclipse Maps"
        },
        {
          "url":"https://www.exploratorium.edu/eclipse/2026-total-solar-eclipse-guide",
          "title":"Guide to the 2026 Total Solar Eclipse - Exploratorium"
        },
        {
          "url":"https://science.nasa.gov/eclipses/future-eclipses/",
          "title":"Future Eclipses - NASA Science"
        }
      ]
    },
    "error":null,
    "request":{
      "method":"GET",
      "params":{
        "query":"When is the next solar eclipse visible from Europe?"
      },
      "payload":[
        
      ],
      "endpoint":"/v1/search",
      "served_at":"2025-11-08T13:27:18.006Z",
      "cache_info":{
        "cached_at":null,
        "is_cached":false,
        "expires_at":null
      },
      "elapsed_ms":4285,
      "status_code":200,
      "requested_at":"2025-11-08T13:27:13.721Z"
    },
    "success":true,
    "uapi_version":"1.2.5",
    "schema_version":"v1",
    "deprecation_warnings":[
      
    ]
  }
  ```
</ResponseExample>

<Note>
  `data.answer_text` is your directly usable answer. `data.sources` is a structured list of citations you can display, log, or validate against.
</Note>


## OpenAPI

````yaml GET /v1/search
openapi: 3.1.0
info:
  title: uAPI
  description: One API for the entire web.
  version: 1.2.5
servers: []
security: []
paths:
  /v1/search:
    get:
      summary: Search Get
      operationId: search_get_v1_search_get
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
            title: Query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
        - APIKeyHeader: []
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-Valet-Key

````