# Discovery

## Retrieve discovered operations on a zone rendered as OpenAPI schemas

`api_gateway.discovery.get(DiscoveryGetParams**kwargs)  -> DiscoveryGetResponse`

**get** `/zones/{zone_id}/api_gateway/discovery`

Retrieve the most up to date view of discovered operations, rendered as OpenAPI schemas

### Parameters

- `zone_id: str`

  Identifier.

### Returns

- `class DiscoveryGetResponse: …`

  - `schemas: List[object]`

  - `timestamp: datetime`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
discovery = client.api_gateway.discovery.get(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(discovery.schemas)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "schemas": [
      {
        "info": {
          "title": "OpenAPI JSON schema for www.example.com",
          "version": "1.0"
        },
        "openapi": "3.0.0",
        "paths": {
          "... Further paths ...": {},
          "/api/v1/users/{var1}": {
            "get": {
              "parameters": [
                {
                  "in": "path",
                  "name": "var1",
                  "required": true,
                  "schema": {
                    "type": "string"
                  }
                }
              ]
            }
          }
        },
        "servers": [
          {
            "url": "www.example.com"
          }
        ]
      }
    ],
    "timestamp": "2014-01-01T05:20:00.12345Z"
  },
  "success": true
}
```

## Domain Types

### Discovery Operation

- `class DiscoveryOperation: …`

  - `id: str`

    UUID.

  - `endpoint: str`

    The endpoint which can contain path parameter templates in curly braces, each will be replaced from left to right with {varN}, starting with {var1}, during insertion. This will further be Cloudflare-normalized upon insertion. See: https://developers.cloudflare.com/rules/normalization/how-it-works/.

  - `host: str`

    RFC3986-compliant host.

  - `last_updated: datetime`

  - `method: Literal["GET", "POST", "HEAD", 6 more]`

    The HTTP method used to access the endpoint.

    - `"GET"`

    - `"POST"`

    - `"HEAD"`

    - `"OPTIONS"`

    - `"PUT"`

    - `"DELETE"`

    - `"CONNECT"`

    - `"PATCH"`

    - `"TRACE"`

  - `origin: List[Literal["ML", "SessionIdentifier", "LabelDiscovery"]]`

    API discovery engine(s) that discovered this operation

    - `"ML"`

    - `"SessionIdentifier"`

    - `"LabelDiscovery"`

  - `state: Literal["review", "saved", "ignored"]`

    State of operation in API Discovery

    * `review` - Operation is not saved into API Shield Endpoint Management
    * `saved` - Operation is saved into API Shield Endpoint Management
    * `ignored` - Operation is marked as ignored

    - `"review"`

    - `"saved"`

    - `"ignored"`

  - `features: Optional[Features]`

    - `traffic_stats: Optional[FeaturesTrafficStats]`

      - `last_updated: datetime`

      - `period_seconds: int`

        The period in seconds these statistics were computed over

      - `requests: float`

        The average number of requests seen during this period

### Discovery Get Response

- `class DiscoveryGetResponse: …`

  - `schemas: List[object]`

  - `timestamp: datetime`

# Operations

## Retrieve discovered operations on a zone

`api_gateway.discovery.operations.list(OperationListParams**kwargs)  -> SyncV4PagePaginationArray[DiscoveryOperation]`

**get** `/zones/{zone_id}/api_gateway/discovery/operations`

Retrieve the most up to date view of discovered operations

### Parameters

- `zone_id: str`

  Identifier.

- `diff: Optional[bool]`

  When `true`, only return API Discovery results that are not saved into API Shield Endpoint Management

- `direction: Optional[Literal["asc", "desc"]]`

  Direction to order results.

  - `"asc"`

  - `"desc"`

- `endpoint: Optional[str]`

  Filter results to only include endpoints containing this pattern.

- `host: Optional[SequenceNotStr[str]]`

  Filter results to only include the specified hosts.

- `method: Optional[SequenceNotStr[str]]`

  Filter results to only include the specified HTTP methods.

- `order: Optional[Literal["host", "method", "endpoint", 2 more]]`

  Field to order by

  - `"host"`

  - `"method"`

  - `"endpoint"`

  - `"traffic_stats.requests"`

  - `"traffic_stats.last_updated"`

- `origin: Optional[Literal["ML", "SessionIdentifier", "LabelDiscovery"]]`

  Filter results to only include discovery results sourced from a particular discovery engine

  * `ML` - Discovered operations that were sourced using ML API Discovery
  * `SessionIdentifier` - Discovered operations that were sourced using Session Identifier API Discovery

  - `"ML"`

  - `"SessionIdentifier"`

  - `"LabelDiscovery"`

- `page: Optional[int]`

  Page number of paginated results.

- `per_page: Optional[int]`

  Maximum number of results per page.

- `state: Optional[Literal["review", "saved", "ignored"]]`

  Filter results to only include discovery results in a particular state. States are as follows

  * `review` - Discovered operations that are not saved into API Shield Endpoint Management
  * `saved` - Discovered operations that are already saved into API Shield Endpoint Management
  * `ignored` - Discovered operations that have been marked as ignored

  - `"review"`

  - `"saved"`

  - `"ignored"`

### Returns

- `class DiscoveryOperation: …`

  - `id: str`

    UUID.

  - `endpoint: str`

    The endpoint which can contain path parameter templates in curly braces, each will be replaced from left to right with {varN}, starting with {var1}, during insertion. This will further be Cloudflare-normalized upon insertion. See: https://developers.cloudflare.com/rules/normalization/how-it-works/.

  - `host: str`

    RFC3986-compliant host.

  - `last_updated: datetime`

  - `method: Literal["GET", "POST", "HEAD", 6 more]`

    The HTTP method used to access the endpoint.

    - `"GET"`

    - `"POST"`

    - `"HEAD"`

    - `"OPTIONS"`

    - `"PUT"`

    - `"DELETE"`

    - `"CONNECT"`

    - `"PATCH"`

    - `"TRACE"`

  - `origin: List[Literal["ML", "SessionIdentifier", "LabelDiscovery"]]`

    API discovery engine(s) that discovered this operation

    - `"ML"`

    - `"SessionIdentifier"`

    - `"LabelDiscovery"`

  - `state: Literal["review", "saved", "ignored"]`

    State of operation in API Discovery

    * `review` - Operation is not saved into API Shield Endpoint Management
    * `saved` - Operation is saved into API Shield Endpoint Management
    * `ignored` - Operation is marked as ignored

    - `"review"`

    - `"saved"`

    - `"ignored"`

  - `features: Optional[Features]`

    - `traffic_stats: Optional[FeaturesTrafficStats]`

      - `last_updated: datetime`

      - `period_seconds: int`

        The period in seconds these statistics were computed over

      - `requests: float`

        The average number of requests seen during this period

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.api_gateway.discovery.operations.list(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
page = page.result[0]
print(page.id)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": [
    {
      "id": "f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
      "endpoint": "/api/v1/users/{var1}",
      "host": "www.example.com",
      "last_updated": "2014-01-01T05:20:00.12345Z",
      "method": "GET",
      "origin": [
        "ML"
      ],
      "state": "review",
      "features": {
        "traffic_stats": {
          "last_updated": "2014-01-01T05:20:00.12345Z",
          "period_seconds": 3600,
          "requests": 1987.06
        }
      }
    }
  ],
  "success": true,
  "result_info": {
    "count": 1,
    "page": 1,
    "per_page": 20,
    "total_count": 2000,
    "total_pages": 100
  }
}
```

## Patch discovered operation

`api_gateway.discovery.operations.edit(stroperation_id, OperationEditParams**kwargs)  -> OperationEditResponse`

**patch** `/zones/{zone_id}/api_gateway/discovery/operations/{operation_id}`

Update the `state` on a discovered operation

### Parameters

- `zone_id: str`

  Identifier.

- `operation_id: str`

  UUID.

- `state: Optional[Literal["review", "ignored"]]`

  Mark state of operation in API Discovery

  * `review` - Mark operation as for review
  * `ignored` - Mark operation as ignored

  - `"review"`

  - `"ignored"`

### Returns

- `class OperationEditResponse: …`

  - `state: Optional[Literal["review", "saved", "ignored"]]`

    State of operation in API Discovery

    * `review` - Operation is not saved into API Shield Endpoint Management
    * `saved` - Operation is saved into API Shield Endpoint Management
    * `ignored` - Operation is marked as ignored

    - `"review"`

    - `"saved"`

    - `"ignored"`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.api_gateway.discovery.operations.edit(
    operation_id="f174e90a-fafe-4643-bbbc-4a0ed4fc8415",
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(response.state)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "state": "review"
  },
  "success": true
}
```

## Patch discovered operations

`api_gateway.discovery.operations.bulk_edit(OperationBulkEditParams**kwargs)  -> OperationBulkEditResponse`

**patch** `/zones/{zone_id}/api_gateway/discovery/operations`

Update the `state` on one or more discovered operations

### Parameters

- `zone_id: str`

  Identifier.

- `body: Dict[str, Body]`

  - `state: Optional[Literal["review", "ignored"]]`

    Mark state of operation in API Discovery

    * `review` - Mark operation as for review
    * `ignored` - Mark operation as ignored

    - `"review"`

    - `"ignored"`

### Returns

- `Dict[str, OperationBulkEditResponseItem]`

  - `state: Optional[Literal["review", "ignored"]]`

    Mark state of operation in API Discovery

    * `review` - Mark operation as for review
    * `ignored` - Mark operation as ignored

    - `"review"`

    - `"ignored"`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.api_gateway.discovery.operations.bulk_edit(
    zone_id="023e105f4ecef8ad9ca31a8372d0c353",
    body={
        "3818d821-5901-4147-a474-f5f5aec1d54e": {},
        "b17c8043-99a0-4202-b7d9-8f7cdbee02cd": {},
    },
)
print(response)
```

#### Response

```json
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "3818d821-5901-4147-a474-f5f5aec1d54e": {
      "state": "ignored"
    },
    "b17c8043-99a0-4202-b7d9-8f7cdbee02cd": {
      "state": "review"
    }
  },
  "success": true
}
```

## Domain Types

### Operation Edit Response

- `class OperationEditResponse: …`

  - `state: Optional[Literal["review", "saved", "ignored"]]`

    State of operation in API Discovery

    * `review` - Operation is not saved into API Shield Endpoint Management
    * `saved` - Operation is saved into API Shield Endpoint Management
    * `ignored` - Operation is marked as ignored

    - `"review"`

    - `"saved"`

    - `"ignored"`

### Operation Bulk Edit Response

- `Dict[str, OperationBulkEditResponseItem]`

  - `state: Optional[Literal["review", "ignored"]]`

    Mark state of operation in API Discovery

    * `review` - Mark operation as for review
    * `ignored` - Mark operation as ignored

    - `"review"`

    - `"ignored"`