> ## Documentation Index > Fetch the complete documentation index at: https://docs.terrapinfinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Bond Search > This endpoint returns a list of US agency bonds with a small set of fields. It is intended for search according to the filters provided. ## OpenAPI ````yaml post /api/v1/agency_search openapi: 3.0.0 info: title: Terrapin API version: 1.0.0 servers: - url: https://terrapinfinance.com variables: {} security: - authorization: [] tags: [] paths: /api/v1/agency_search: post: tags: [] summary: US agency bond search description: >- This endpoint returns a list of US agency bonds with a small set of fields. It is intended for search according to the filters provided. operationId: post_agency_search parameters: [] requestBody: content: application/json: example: isins: - US3134HCZH51 schema: additionalProperties: false properties: coupon_max: description: Maximum coupon rate of the agency bond (in percentage). type: number x-struct: null x-validate: null coupon_min: description: Minimum coupon rate of the agency bond (in percentage). type: number x-struct: null x-validate: null full_reference_data: description: >- Return full reference data as in from /api/v1/agency_reference. This option requires a special account tier. type: boolean x-struct: null x-validate: null interest_types: description: > Types of interest: - `fixed rate`: The bond pays a fixed interest rate throughout its life. - `zero rate / discount rate`: A bond that does not pay or accrue interest. - `variable rate`: The bond's interest rate can change over time, typically based on a reference rate or formula (e.g., SOFR, CPI). - `step rate`: The bond's interest rate increases ("steps up") at predetermined intervals. items: enum: - fixed rate - step rate - variable rate - zero rate / discount rate nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-transform: downcase x-validate: null is_callable: description: Filter by whether the bond is callable. type: boolean x-struct: null x-validate: null isins: description: >- International Securities Identification Number (ISIN), unique 12-character code for the security. items: example: US3134HCZH51 maxLength: 12 minLength: 12 nullable: false type: string x-struct: null x-validate: null type: array x-check: valid_check_digit x-check-error: Invalid ISIN check digit x-struct: null x-transform: upcase x-validate: null issue_date_max: description: >- Maximum issue date of the agency bond in ISO-8601 format (YYYY-MM-DD). format: date type: string x-struct: null x-validate: null issue_date_min: description: >- Minimum issue date of the agency bond in ISO-8601 format (YYYY-MM-DD). format: date type: string x-struct: null x-validate: null issued_amount_max: description: Maximum size of total amount issued (in nominal value). minimum: 0 type: integer x-struct: null x-validate: null issued_amount_min: description: Minimum size of total amount issued (in nominal value). minimum: 0 type: integer x-struct: null x-validate: null issuer_name: description: Name of the issuing agency. enum: - FEDERAL HOME LOAN MORTGAGE CORPORATION - FEDERAL NATIONAL MORTGAGE ASSOCIATION nullable: false type: string x-struct: null x-validate: null limit: default: 100 description: >- Result count limit. E.g. if total number of results is 1450, limit of 100 with offset of 0 would return the first 100 results. A limit of 0 returns no results but still includes the total count, which is useful for checking how many results match the given filters. minimum: 0 type: integer x-struct: null x-validate: null maturity_date_max: description: >- Maximum maturity date of the agency bond in ISO-8601 format (YYYY-MM-DD). format: date type: string x-struct: null x-validate: null maturity_date_min: description: >- Minimum maturity date of the agency bond in ISO-8601 format (YYYY-MM-DD). format: date type: string x-struct: null x-validate: null offset: default: 0 description: >- Offset for query pagination. E.g. limit of 100 with offset of 50 would return the results 50 to 150. minimum: 0 type: integer x-struct: null x-validate: null sort: description: Sort order. Prefix with '-' for descending order. items: enum: - '-interest_rate' - '-interest_type' - '-is_callable' - '-isin' - '-issuer_name' - '-maturity_date' - '-ticker' - interest_rate - interest_type - is_callable - isin - issuer_name - maturity_date - ticker type: string x-struct: null x-validate: null type: array x-struct: null x-transform: downcase x-validate: null values_updated_since: anyOf: - deprecated: true format: date type: string x-struct: null x-validate: null - format: date-time type: string x-struct: null x-validate: null description: > Optional filter to only return bonds whose reference data has been updated since the given UTC instant. Accepts an ISO-8601 date-time (YYYY-MM-DDThh:mm:ssZ), which is recommended since reference data can be updated multiple times per day. A plain ISO-8601 date (YYYY-MM-DD) is also accepted for backwards compatibility but is **deprecated**, as it only resolves to the start of that day (00:00:00 UTC). nullable: false x-struct: null x-validate: null type: object x-struct: null x-validate: null required: true responses: '200': content: application/json: example: data: - interest_rate: 5.2 interest_type: fixed rate is_callable: true isin: US3134HCZH51 issuer_name: FEDERAL HOME LOAN MORTGAGE CORPORATION maturity_date: '2056-03-16' ticker: FHLMC 5.2 03/16/56 total: 1 schema: additionalProperties: false properties: data: description: List of response data objects, often capped to 1000. items: additionalProperties: false properties: interest_rate: description: > Interest rate or coupon of the bond, expressed as a percentage of the bond's face value. nullable: true oneOf: - nullable: true type: number x-struct: null x-validate: null - properties: benchmark: type: string x-struct: null x-validate: null pct_of_benchmark: nullable: true type: number x-struct: null x-validate: null spread_in_bps: nullable: true type: number x-struct: null x-validate: null type: object x-struct: null x-validate: null x-struct: null x-validate: null interest_type: description: > Type of interest: - `fixed rate`: The bond pays a fixed interest rate throughout its life. - `zero rate / discount rate`: A bond that does not pay or accrue interest. - `variable rate`: The bond's interest rate can change over time, typically based on a reference rate or formula (e.g., SOFR, CPI). - `step rate`: The bond's interest rate increases ("steps up") at predetermined intervals. enum: - fixed rate - step rate - variable rate - zero rate / discount rate nullable: true type: string x-struct: null x-validate: null is_callable: description: | Whether the bond is callable before maturity. nullable: true type: boolean x-struct: null x-validate: null isin: description: >- International Securities Identification Number (ISIN), unique 12-character code for the security. example: US3134HCZH51 maxLength: 12 minLength: 12 nullable: false type: string x-check: valid_check_digit x-check-error: Invalid ISIN check digit x-struct: null x-transform: upcase x-validate: null issuer_name: description: Name of the issuing agency. enum: - FEDERAL HOME LOAN MORTGAGE CORPORATION - FEDERAL NATIONAL MORTGAGE ASSOCIATION nullable: false type: string x-struct: null x-validate: null maturity_date: description: >- Date when the bond principal is due to be repaid in ISO-8601 format (YYYY-MM-DD). format: date nullable: false type: string x-struct: null x-validate: null ticker: description: Bond ticker symbol. example: FHLMC 5.2 03/16/56 nullable: true type: string x-struct: null x-validate: null required: - interest_rate - interest_type - is_callable - isin - issuer_name - maturity_date - ticker type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null total: description: >- Total number of results in the database that match the query filters. type: integer x-struct: null x-validate: null required: - data - total title: AgencySearchResponse type: object x-struct: null x-validate: null description: Partial reference data '401': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Unauthorized type: string x-struct: null x-validate: null reason: example: >- Your account tier does not allow this operation. Contact team@terrapinfinance.com for an upgrade. type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Unauthorized '402': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Payment Required type: string x-struct: null x-validate: null reason: example: >- You have run out of your granted quota for this resource as defined by your account tier. Contact team@terrapinfinance.com for an upgrade. type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Payment Required '403': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Forbidden type: string x-struct: null x-validate: null reason: example: >- Your account tier does not allow this operation. Contact team@terrapinfinance.com for an upgrade. type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Forbidden '422': content: application/json: schema: properties: errors: items: properties: detail: example: 'Invalid string. Got: integer' type: string x-struct: null x-validate: null source: properties: pointer: example: /isins/0 type: string x-struct: null x-validate: null required: - pointer type: object x-struct: null x-validate: null title: example: Invalid value type: string x-struct: null x-validate: null required: - detail - source - title type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Unprocessable Entity '429': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Too Many Requests type: string x-struct: null x-validate: null reason: type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Too Many Requests '500': content: application/json: schema: additionalProperties: false properties: errors: items: additionalProperties: false properties: detail: example: Internal Server Error type: string x-struct: null x-validate: null reason: type: string x-struct: null x-validate: null required: - detail type: object x-struct: null x-validate: null type: array x-struct: null x-validate: null required: - errors type: object x-struct: null x-validate: null description: Internal Server Error callbacks: {} components: securitySchemes: authorization: scheme: bearer type: http ````