> ## 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 municipal bonds with a small set of fields. It is intended for search according to the filters provided. ## OpenAPI ````yaml post /api/v1/muni_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/muni_search: post: tags: [] summary: US municipal bond search description: >- This endpoint returns a list of US municipal bonds with a small set of fields. It is intended for search according to the filters provided. operationId: post_muni_search parameters: [] requestBody: content: application/json: example: interest_types: - variable rate issuer_name: ABAG Finance Authority for Nonprofit Corporations maturity_date_min: '2030-10-30' schema: additionalProperties: false properties: advisors: description: > Optional filter to return only bonds with a specific advisor. items: type: string x-struct: null x-validate: null nullable: false type: array x-struct: null x-validate: null coupon_max: description: Maximum coupon rate of the municipal bond (in percentage). type: number x-struct: null x-validate: null coupon_min: description: Minimum coupon rate of the municipal bond (in percentage). type: number x-struct: null x-validate: null entity_id: description: The ID of the issuer or obligor to filter by. type: integer x-struct: null x-validate: null full_reference_data: description: >- Return full reference data as in from /api/v1/muni_reference. This option requires a special account tier. type: boolean x-struct: null x-validate: null include_bonds_without_os: default: false description: > Whether to include municipal bonds for which a final official statement is not found or is not yet available. This will most often correspond to recently issued bonds. The fields in these bonds are provided on a best-effort basis from the limited information available at that stage. type: boolean x-struct: null x-validate: null include_callable: description: > Whether to include callable municipal bonds, bonds that can be redeemed before maturity. 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. - `cab`: Capital Appreciation Bond (CAB), interest accrues and is paid at maturity rather than periodically. - `variable rate`: The bond's interest rate can change over time, typically based on a reference rate or formula (e.g., SOFR, CPI). - `term rate`: The bond pays interest at a rate set for a specific term or period. - `cab-to-fixed`: The bond starts as a capital appreciation bond and converts to a fixed rate bond. - `step rate`: The bond's interest rate increases ("steps up") at predetermined intervals. - `zero rate / discount rate`: A bond that does not pay or accrue interest. items: enum: - cab - cab-to-fixed - fixed rate - step rate - term 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_insured: description: | Whether the bond is insured by a bond insurance company. nullable: true type: boolean x-struct: null x-validate: null isins: description: >- International Securities Identification Number (ISIN), unique 12-character code for the security. items: example: US64966HW301 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 municipal 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 municipal 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 entity (municipality, district, etc.). nullable: false type: string x-struct: null x-validate: null last_traded_since: description: > Optional date filter to only return bonds that have been traded since the specified UTC date in ISO-8601 format (YYYY-MM-DD). format: date 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 municipal 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 municipal 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 sectors: description: |2 Sector of the municipal bond: - `education`: Educational institutions (schools, universities, colleges). - `local`: Local government entities (cities, counties, towns). - `utilities`: Utility companies and infrastructure. - `transportation`: Transportation and transit systems. - `state`: State government entities. - `healthcare`: Healthcare facilities and medical institutions. - `housing`: Housing and residential development. - `industrial`: Industrial and economic development. - `tobacco`: Tobacco settlement bonds. items: enum: - education - healthcare - housing - industrial - local - state - tobacco - transportation - utilities nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-transform: downcase x-validate: null sort: description: Sort order. Prefix with '-' for descending order. items: enum: - '-has_official_statement' - '-interest_rate' - '-interest_type' - '-is_callable' - '-isin' - '-issue_date' - '-issuer_name' - '-maturity_date' - '-rating_group' - '-state' - '-ticker' - has_official_statement - interest_rate - interest_type - is_callable - isin - issue_date - issuer_name - maturity_date - rating_group - state - ticker type: string x-struct: null x-validate: null type: array x-struct: null x-transform: downcase x-validate: null sources_of_repayment: description: > Sources of repayment for municipal bonds. Determines how the bond will be repaid. - `Revenue`: Repaid from specific project revenues (e.g., tolls, utilities). - `General Obligation`: Repaid from the issuer's general fund. - `Double Barrel`: A combination of General Obligation and Revenue sources. items: enum: - Double Barrel - General Obligation - Revenue nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-validate: null states: description: > US states or territory where the bond is issued (ANSI 2-letter code). items: example: IL maxLength: 2 minLength: 2 nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-transform: upcase x-validate: null underwriters: description: > Optional filter to return only bonds issued through a specific underwriter. items: type: string x-struct: null x-validate: null nullable: false type: array x-struct: null x-validate: null use_categories: description: > Filter bonds by use categories (middle level of use of funds hierarchy). For the complete taxonomy, see the [Use of Funds Taxonomy](https://docs.terrapinfinance.com/use_of_funds_taxonomy) reference page. items: enum: - airport - bridges - communication - culture - economic development - electrical - essential services - gas - gas prepay - general purpose - health system - higher education - hospitals - industrial development - military housing - miscellaneous - multi-family housing - parking - port - power - pre-school - primary and secondary education - public housing - public transit - recreational - roads - senior living - single family housing - student loan - waste removal - water and sewer nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-transform: downcase x-validate: null use_sectors: description: > Filter bonds by use sectors (top level of use of funds hierarchy). For the complete taxonomy, see the [Use of Funds Taxonomy](https://docs.terrapinfinance.com/use_of_funds_taxonomy) reference page. items: enum: - development - education - government - healthcare - housing - miscellaneous - recreation - securitized - transportation - utility nullable: false type: string x-struct: null x-validate: null type: array x-struct: null x-transform: downcase x-validate: null uses_of_proceeds: description: > Filter bonds by uses of proceeds (most granular level of use of funds hierarchy). For the complete taxonomy, see the [Use of Funds Taxonomy](https://docs.terrapinfinance.com/use_of_funds_taxonomy) reference page. items: enum: - airport - alternative source power - assisted living - broadband - buses - charter school - coal power - combined port authority - community centre - community college - continuing care retirement community - correctional facilities - courts - critical access hospital - development district - electrical infrastructure - ferries - fire - flood control - gas infrastructure - gas power - gas prepay - health system - hospitality - independent living - industrial development - irrigation - library - local hfa multi-family housing - local hfa single family housing - local standalone multi-family housing - local standalone single family housing - military housing - miscellaneous - museum - non-toll bridges - non-toll roads - nuclear power - nursing home - office buildings - parking facilities - parks - police - pollution control - pre-school and daycare - private college - public buildings - public college - public housing - public school district - regional toll bridges - regional toll roads - sewer - shopping centres - solar power - specialty hospital - stadium - standalone hospital - standalone port - standalone public school - state hfa multi-family housing - state hfa single family housing - state toll bridges - state toll roads - storm water - student housing - student loan - telephone - trains - tribal - waste removal - water - wind power nullable: false 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: - has_official_statement: true interest_rate: 5 interest_type: fixed rate is_callable: true isin: US00037CUQ13 issuer_name: ABAG Finance Authority for Nonprofit Corporations maturity_date: '2035-11-15' rating_group: investment_grade state: CA ticker: CA AFAGEN 5 11/15/2035 total: 1 schema: additionalProperties: false properties: data: description: List of response data objects, often capped to 1000. items: additionalProperties: false properties: has_official_statement: description: > Whether the bond has an official statement published. Pre official statement bonds only have a limited set of fields available that are provided on a best-effort basis. nullable: false type: boolean x-struct: null x-validate: null 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: > The Type of interest: - `fixed rate`: The bond pays a fixed interest rate throughout its life. - `cab`: Capital Appreciation Bond (CAB), interest accrues and is paid at maturity rather than periodically. - `variable rate`: The bond's interest rate can change over time, typically based on a reference rate or formula (e.g., SOFR, CPI). - `term rate`: The bond pays interest at a rate set for a specific term or period. - `cab-to-fixed`: The bond starts as a capital appreciation bond and converts to a fixed rate bond. - `step rate`: The bond's interest rate increases ("steps up") at predetermined intervals. - `zero rate / discount rate`: A bond that does not pay or accrue interest. enum: - cab - cab-to-fixed - fixed rate - step rate - term 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: false type: boolean x-struct: null x-validate: null isin: description: >- International Securities Identification Number (ISIN), unique 12-character code for the security. example: US64966HW301 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 entity (municipality, district, etc.). example: School District Number 172 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 rating_group: description: > Credit rating group: - `investment_grade`: Bonds with high credit quality, typically considered safe and low risk. - `high_yield`: Bonds with lower credit quality, typically considered riskier and higher yield. enum: - high_yield - investment_grade nullable: true type: string x-struct: null x-validate: null state: description: > US state or territory where the bond is issued (ANSI 2-letter code). example: IL maxLength: 2 minLength: 2 nullable: false type: string x-struct: null x-validate: null ticker: description: Bond ticker symbol. example: IL ADASCD 5 02/01/2035 nullable: true type: string x-struct: null x-validate: null required: - has_official_statement - interest_rate - interest_type - is_callable - isin - issuer_name - maturity_date - rating_group - state - 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: MuniSearchResponse 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 ````