# Sampling Structures

Efficiently expand into chemical space by sampling from generative Deep-Learning models around an underlying distribution of molecules. With the ability to easily generate hundreds of thousands of unique structures in minutes, building a diverse library of molecular structures reduces the time and cost associated with traditional first Hit Identification methods - additionally see our other solutions to further improve Drug Discovery pipeline stages.

**Considerations:**

* Sampling speed is limited by API request rate limits and data transfer bottlenecks. For larger sampling requirements, contact us to discuss custom solutions.
* Structures are generated as unique SMILES within a single request, however duplicate structures may be generated across multiple requests. See individual model metadata for more information on uniqueness rates.

See [here](https://docs.pending.ai/capabilities/generative-ai) for more information on our **Generative AI** capability.

## List samples

> Retrieve a list of samples. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.

```json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v1"},"tags":[{"description":"\nEfficiently expand into chemical space by sampling from generative Deep-Learning models\naround an underlying distribution of molecules. With the ability to easily generate\nhundreds of thousands of unique structures in minutes, building a diverse library of\nmolecular structures reduces the time and cost associated with traditional first\nHit Identification methods - additionally see our other solutions to further improve\nDrug Discovery pipeline stages.\n\n**Considerations:**\n\n- Sampling speed is limited by API request rate limits and data transfer bottlenecks.\nFor larger sampling requirements, contact us to discuss custom solutions.\n- Structures are generated as unique SMILES within a single request, however\nduplicate structures may be generated across multiple requests. See individual model\nmetadata for more information on uniqueness rates.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n","name":"Samples"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/generator/v1"}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{}}},"type":"oauth2"}},"schemas":{"ResourceList_ListOutputItem_":{"properties":{"data":{"description":"A list containing the retrieved objects. The list can contain fewer\nobjects than requested if a smaller number of results were found.","items":{"$ref":"#/components/schemas/ListOutputItem"},"title":"Data","type":"array"},"has_more":{"description":"A boolean flag that indicates whether there are more items available\nto be fetched on subsequent pages. Used for pagination control.","title":"Has More","type":"boolean"},"object":{"default":"list","description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"}},"required":["data","has_more"],"title":"ResourceList[Sample.ListOutputItem]","type":"object"},"ListOutputItem":{"description":"A reduced representation of a sample for providing metadata to\nallow for efficient listing. To retrieve sample results, request\nindividual samples by their `id`.","properties":{"created_at":{"description":"Timestamp for when the sample was created.","format":"date-time","title":"Created At","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"model_id":{"description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model.","pattern":"^\\w+$","title":"Model Id","type":"string"},"num_smiles":{"description":"The number of sampled molecules to be generated for the request.","maximum":10000,"minimum":1,"title":"Num Smiles","type":"integer"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"}},"required":["id","object","model_id","num_smiles"],"title":"Sample","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"ResponseValidationError","type":"object"}}},"paths":{"/samples":{"get":{"description":"Retrieve a list of samples. Key-based pagination is supported. See query parameters for more details on how to retrieve the next or previous page of results.","operationId":"list_samples_samples_get","parameters":[{"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","in":"query","name":"limit","required":false,"schema":{"default":5,"description":"Limit the number of resources returned within the `data` field of the paged response. The field may contain fewer items than the specified limit when there are not enough items to return.","maximum":100,"minimum":1,"title":"Limit","type":"integer"}},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","in":"query","name":"next-page","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the next 'page', or those that were submitted before the matched resource (reverse chronological order).","title":"Next-Page"}},{"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","in":"query","name":"prev-page","required":false,"schema":{"anyOf":[{"maxLength":255,"minLength":1,"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"A key used to navigate pagination results. The given value must match an `id` for the specific resource `object` type. If provided, the paged response will contain resources from the previous 'page', or those that were submitted after the matched resource (reverse chronological order).","title":"Prev-Page"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceList_ListOutputItem_"}}},"description":"Returns a list of samples."},"400":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Request contained invalid data."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}},"description":"Response Validation Error"}},"summary":"List samples","tags":["Samples"]}}}}
```

## Create a sample

> Create a sample by generating molecules from a specific model. When no model is provided, any will be used that is readily available.

```json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v1"},"tags":[{"description":"\nEfficiently expand into chemical space by sampling from generative Deep-Learning models\naround an underlying distribution of molecules. With the ability to easily generate\nhundreds of thousands of unique structures in minutes, building a diverse library of\nmolecular structures reduces the time and cost associated with traditional first\nHit Identification methods - additionally see our other solutions to further improve\nDrug Discovery pipeline stages.\n\n**Considerations:**\n\n- Sampling speed is limited by API request rate limits and data transfer bottlenecks.\nFor larger sampling requirements, contact us to discuss custom solutions.\n- Structures are generated as unique SMILES within a single request, however\nduplicate structures may be generated across multiple requests. See individual model\nmetadata for more information on uniqueness rates.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n","name":"Samples"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/generator/v1"}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{}}},"type":"oauth2"}},"schemas":{"pai_generator__models__samples__Sample__CreateParams":{"description":"Request data for creating a new sample.","properties":{"model_id":{"anyOf":[{"pattern":"^\\w+$","type":"string"},{"type":"null"}],"description":"Optional `id` belonging to a model to use for generating the\nsample. If no model is provided, any will be used that is\nreadily available.","title":"Model Id"},"size":{"description":"The number of sampled molecules to generate for the request.\nMust be a positive integer.","maximum":10000,"minimum":1,"title":"Size","type":"integer"}},"required":["size"],"title":"SampleCreateParams","type":"object"},"SampleResource":{"description":"A sample contains a collection of molecules generated by a machine-\nlearning model on a defined chemical space. Samples represent the\nnovel structures in a SMILES format.","properties":{"created_at":{"description":"Timestamp for when the sample was created.","format":"date-time","title":"Created At","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"model_id":{"description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model.","pattern":"^\\w+$","title":"Model Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"smiles":{"description":"A collection of generated SMILES structures from the model. The\nnumber of structures will correspond to the `num_samples` value\nprovided when creating the sample.","items":{"type":"string"},"title":"Smiles","type":"array"}},"required":["id","object","model_id","smiles"],"title":"Sample","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"ResponseValidationError","type":"object"}}},"paths":{"/samples":{"post":{"description":"Create a sample by generating molecules from a specific model. When no model is provided, any will be used that is readily available.","operationId":"create_sample_samples_post","parameters":[{"description":"An optional header to be provided when accepting Base64 compressed response content. Providing the header value `gzip` yields gzipped Base64-encoded content for the response body.","in":"header","name":"accept-encoding","required":false,"schema":{"default":"*","description":"An optional header to be provided when accepting Base64 compressed response content. Providing the header value `gzip` yields gzipped Base64-encoded content for the response body.","enum":["gzip","*"],"title":"Accept-Encoding","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/pai_generator__models__samples__Sample__CreateParams"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleResource"}}},"description":"Returns the sample."},"400":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Request contained invalid data."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}},"description":"Response Validation Error"}},"summary":"Create a sample","tags":["Samples"]}}}}
```

## Retrieve a sample

> Retrieves a sample and all generated structures. This is designed to allow retrieving any samples previously generated.

```json
{"openapi":"3.1.0","info":{"title":"PAI Generator","version":"v1"},"tags":[{"description":"\nEfficiently expand into chemical space by sampling from generative Deep-Learning models\naround an underlying distribution of molecules. With the ability to easily generate\nhundreds of thousands of unique structures in minutes, building a diverse library of\nmolecular structures reduces the time and cost associated with traditional first\nHit Identification methods - additionally see our other solutions to further improve\nDrug Discovery pipeline stages.\n\n**Considerations:**\n\n- Sampling speed is limited by API request rate limits and data transfer bottlenecks.\nFor larger sampling requirements, contact us to discuss custom solutions.\n- Structures are generated as unique SMILES within a single request, however\nduplicate structures may be generated across multiple requests. See individual model\nmetadata for more information on uniqueness rates.\n\nSee [here](https://docs.pending.ai/capabilities/generative-ai)  for more information on\nour **Generative AI** capability.\n","name":"Samples"}],"servers":[{"description":"Pending AI Server","url":"https://api.pending.ai/generator/v1"}],"security":[{"oauth":[""],"token":[""]}],"components":{"securitySchemes":{"oauth":{"description":"OAuth2 authentication.\n\nAuthenticate using the Pending AI [authorization server](https://auth.pending.ai/authorize) through an implicit OAuth2 flow. You will be redirected to a Pending AI login page to authenticate and authorize access to your account. After authorization, you will be redirected back to the original application with an access token. Ensure that the application is registered with Pending AI and/or that the correct redirect URI is configured. Contact Pending AI support for more information if the application is not registered.","flows":{"implicit":{"authorizationUrl":"https://auth.pending.ai/authorize","scopes":{}}},"type":"oauth2"}},"schemas":{"SampleResource":{"description":"A sample contains a collection of molecules generated by a machine-\nlearning model on a defined chemical space. Samples represent the\nnovel structures in a SMILES format.","properties":{"created_at":{"description":"Timestamp for when the sample was created.","format":"date-time","title":"Created At","type":"string"},"id":{"description":"The unique resource identifier.","pattern":"^\\w+$","title":"Resource Id","type":"string"},"model_id":{"description":"An `id` belonging to the model used to generate the sample. The\nvalue can be used to retrieve more information about the model.","pattern":"^\\w+$","title":"Model Id","type":"string"},"object":{"description":"The type of resource.","pattern":"^\\w+$","title":"Resource Object","type":"string"},"smiles":{"description":"A collection of generated SMILES structures from the model. The\nnumber of structures will correspond to the `num_samples` value\nprovided when creating the sample.","items":{"type":"string"},"title":"Smiles","type":"array"}},"required":["id","object","model_id","smiles"],"title":"Sample","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"ResponseValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"ResponseValidationError","type":"object"}}},"paths":{"/samples/{sample_id}":{"get":{"description":"Retrieves a sample and all generated structures. This is designed to allow retrieving any samples previously generated.","operationId":"retrieve_sample_samples__sample_id__get","parameters":[{"description":"A unique identifier for a sample resource.","in":"path","name":"sample_id","required":true,"schema":{"description":"A unique identifier for a sample resource.","maxLength":255,"minLength":1,"pattern":"^\\w+$","title":"Sample Id","type":"string"}},{"description":"An optional header to be provided when accepting Base64 compressed response content. Providing the header value `gzip` yields gzipped Base64-encoded content for the response body.","in":"header","name":"accept-encoding","required":false,"schema":{"default":"*","description":"An optional header to be provided when accepting Base64 compressed response content. Providing the header value `gzip` yields gzipped Base64-encoded content for the response body.","enum":["gzip","*"],"title":"Accept-Encoding","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleResource"}}},"description":"Returns the sample."},"404":{"content":{"application/json":{"schema":{"title":"Return","type":"null"}}},"description":"Sample resource not found."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseValidationError"}}},"description":"Response Validation Error"}},"summary":"Retrieve a sample","tags":["Samples"]}}}}
```